feat(compiler): descriptions in generated JSON schemas

packages/@winglang/wingc/src/docs.rs

@@ -6,7 +6,7 @@ use regex::Regex;
 use crate::{
 	ast::{AccessModifier, Phase},
 	closure_transform::CLOSURE_CLASS_PREFIX,
-	jsify::codemaker::CodeMaker,
+	jsify::{codemaker::CodeMaker, escape_javascript_string},
 	type_check::{
 		jsii_importer::is_construct_base, symbol_env::SymbolEnvKind, Class, ClassLike, Enum, FunctionSignature, Interface,
 		Namespace, Struct, SymbolKind, Type, TypeRef, VariableInfo, VariableKind, CLASS_INFLIGHT_INIT_NAME,
@@ -47,6 +47,50 @@ impl Docs {
 		markdown.to_string().trim().to_string()
 	}
 
+	pub fn to_escaped_string(&self) -> String {
+		let mut contents = String::new();
+		if let Some(summary) = &self.summary {
+			contents.push_str(summary);
+		}
+		if let Some(remarks) = &self.remarks {
+			contents.push_str("\n\n");
+			contents.push_str(remarks);
+		}
+		if let Some(example) = &self.example {
+			contents.push_str("\n@example ");
+			contents.push_str(example);
+		}
+		if let Some(returns) = &self.returns {
+			contents.push_str("\n@returns ");
+			contents.push_str(returns);
+		}
+		if let Some(deprecated) = &self.deprecated {
+			contents.push_str("\n@deprecated ");
+			contents.push_str(deprecated);
+		}
+		if let Some(see) = &self.see {
+			contents.push_str("\n@see ");
+			contents.push_str(see);
+		}
+		if let Some(default) = &self.default {
+			contents.push_str("\n@default ");
+			contents.push_str(default);
+		}
+		if let Some(stability) = &self.stability {
+			contents.push_str("\n@stability ");
+			contents.push_str(stability);
+		}
+		if let Some(_) = &self.subclassable {
+			contents.push_str("\n@subclassable");
+		}
+		for (k, v) in self.custom.iter() {
+			contents.push_str(&format!("\n@{} ", k));
+			contents.push_str(v);
+		}
+
+		escape_javascript_string(&contents)
+	}
+
 	pub(crate) fn with_summary(summary: &str) -> Docs {
 		Docs {
 			summary: Some(summary.to_string()),

packages/@winglang/wingc/src/jsify.rs

@@ -380,7 +380,7 @@ impl<'a> JSifier<'a> {
 
 			code.line(format!(
 				"const {flat_name} = $stdlib.std.Struct._createJsonSchema({});",
-				schema_code.to_string().replace("\n", "").replace(" ", "")
+				schema_code.to_string()
 			));
 		}
 		code
@@ -2704,7 +2704,7 @@ fn lookup_span(span: &WingSpan, files: &Files) -> String {
 	result
 }
 
-fn escape_javascript_string(s: &str) -> String {
+pub fn escape_javascript_string(s: &str) -> String {
 	let mut result = String::new();
 
 	// escape all escapable characters -- see the section "Escape sequences" in

packages/@winglang/wingc/src/json_schema_generator.rs

@@ -1,4 +1,5 @@
 use crate::{
+	docs::Docs,
 	jsify::{codemaker::CodeMaker, JSifier},
 	type_check::{symbol_env::SymbolEnv, Struct, Type, UnsafeRef},
 };
@@ -13,107 +14,141 @@ impl JsonSchemaGenerator {
 	fn get_struct_env_properties(&self, env: &SymbolEnv) -> CodeMaker {
 		let mut code = CodeMaker::default();
 		for (field_name, entry) in env.symbol_map.iter() {
-			code.line(format!(
-				"{}: {},",
+			let var_info = entry.kind.as_variable().unwrap();
+			let docs = var_info.docs.clone();
+			code.append(format!(
+				"{}:{},",
 				field_name,
-				self.get_struct_schema_field(&entry.kind.as_variable().unwrap().type_)
+				self.get_struct_schema_field(&entry.kind.as_variable().unwrap().type_, docs)
 			));
 		}
 		code
 	}
 
 	fn get_struct_schema_required_fields(&self, env: &SymbolEnv) -> CodeMaker {
 		let mut code = CodeMaker::default();
-		code.open("required: [");
+		code.append("required:[");
 		for (field_name, entry) in env.symbol_map.iter() {
 			if !matches!(*entry.kind.as_variable().unwrap().type_, Type::Optional(_)) {
-				code.line(format!("\"{}\",", field_name));
+				code.append(format!("\"{}\",", field_name));
 			}
 		}
-		code.close("]");
+		code.append("]");
 		code
 	}
 
-	fn get_struct_schema_field(&self, typ: &UnsafeRef<Type>) -> String {
+	fn get_struct_schema_field(&self, typ: &UnsafeRef<Type>, docs: Option<Docs>) -> String {
 		match **typ {
 			Type::String | Type::Number | Type::Boolean => {
-				format!("{{ type: \"{}\" }}", JSifier::jsify_type(typ).unwrap())
+				let jsified_type = JSifier::jsify_type(typ).unwrap();
+				match docs {
+					Some(docs) => format!(
+						"{{type:\"{}\",description:\"{}\"}}",
+						jsified_type,
+						docs.to_escaped_string()
+					),
+					None => format!("{{type:\"{}\"}}", jsified_type),
+				}
 			}
 			Type::Struct(ref s) => {
 				let mut code = CodeMaker::default();
-				code.open("{");
-				code.line("type: \"object\",");
-				code.open("properties: {");
-				code.add_code(self.get_struct_env_properties(&s.env));
-				code.close("},");
-				code.add_code(self.get_struct_schema_required_fields(&s.env));
-				code.close("}");
+				code.append("{");
+				code.append("type:\"object\",");
+				code.append("properties:{");
+				code.append(self.get_struct_env_properties(&s.env));
+				code.append("},");
+				code.append(self.get_struct_schema_required_fields(&s.env));
+				let docs = docs.unwrap_or(s.docs.clone());
+				code.append(format!(",description:\"{}\"", docs.to_escaped_string()));
+				code.append("}");
 				code.to_string()
 			}
 			Type::Array(ref t) | Type::Set(ref t) => {
 				let mut code = CodeMaker::default();
-				code.open("{");
+				code.append("{");
 
-				code.line("type: \"array\",");
+				code.append("type:\"array\"");
 
 				if matches!(**typ, Type::Set(_)) {
-					code.line("uniqueItems: true,");
+					code.append(",uniqueItems:true");
 				}
 
-				code.line(format!("items: {}", self.get_struct_schema_field(t)));
+				code.append(format!(",items:{}", self.get_struct_schema_field(t, None)));
+
+				if let Some(docs) = docs {
+					code.append(format!(",description:\"{}\"", docs.to_escaped_string()));
+				}
 
-				code.close("}");
+				code.append("}");
 				code.to_string()
 			}
 			Type::Map(ref t) => {
 				let mut code = CodeMaker::default();
-				code.open("{");
+				code.append("{");
 
-				code.line("type: \"object\",");
-				code.line(format!(
-					"patternProperties: {{ \".*\": {} }}",
-					self.get_struct_schema_field(t)
+				code.append("type:\"object\",");
+				code.append(format!(
+					"patternProperties: {{\".*\":{}}}",
+					self.get_struct_schema_field(t, None)
 				));
 
-				code.close("}");
+				if let Some(docs) = docs {
+					code.append(format!("description:\"{}\",", docs.to_escaped_string()));
+				}
+
+				code.append("}");
 				code.to_string()
 			}
-			Type::Optional(t) => self.get_struct_schema_field(&t),
-			Type::Json(_) => "{ type: [\"object\", \"string\", \"boolean\", \"number\", \"array\"] }".to_string(),
+			Type::Optional(ref t) => self.get_struct_schema_field(t, docs),
+			Type::Json(_) => match docs {
+				Some(docs) => format!(
+					"{{type:[\"object\",\"string\",\"boolean\",\"number\",\"array\"],description:\"{}\"}}",
+					docs.to_escaped_string()
+				),
+				None => "{type:[\"object\",\"string\",\"boolean\",\"number\",\"array\"]}".to_string(),
+			},
 			Type::Enum(ref enu) => {
 				let choices = enu
 					.values
 					.iter()
 					.map(|(s, _)| format!("\"{}\"", s))
 					.collect::<Vec<String>>()
 					.join(", ");
-				format!("{{ type: \"string\", enum: [{}] }}", choices)
+				let docs = docs.unwrap_or(enu.docs.clone());
+				format!(
+					"{{type:\"string\",enum:[{}],description:\"{}\"}}",
+					choices,
+					docs.to_escaped_string()
+				)
 			}
-			_ => "{ type: \"null\" }".to_string(),
+			_ => match docs {
+				Some(docs) => format!("{{type:\"null\",description:\"{}\" }}", docs.to_escaped_string()),
+				None => "{type:\"null\"}".to_string(),
+			},
 		}
 	}
 
 	pub fn create_from_struct(&self, struct_: &Struct) -> CodeMaker {
 		let mut code = CodeMaker::default();
 
-		code.open("{");
-		code.line(format!("$id: \"/{}\",", struct_.name));
-		code.line("type: \"object\",".to_string());
+		code.append("{");
+		code.append(format!("$id:\"/{}\",", struct_.name));
+		code.append("type:\"object\",".to_string());
 
-		code.open("properties: {");
+		code.append("properties:{");
 
-		code.add_code(self.get_struct_env_properties(&struct_.env));
+		code.append(self.get_struct_env_properties(&struct_.env));
 
 		//close properties
-		code.close("},");
+		code.append("},");
 
-		code.add_code(self.get_struct_schema_required_fields(&struct_.env));
+		code.append(self.get_struct_schema_required_fields(&struct_.env));
 
-		// close schema
-		code.close("}");
+		code.append(format!(",description:\"{}\"", struct_.docs.to_escaped_string()));
 
-		let cleaned = code.to_string().replace("\n", "").replace(" ", "");
+		// close schema
+		code.append("}");
 
-		CodeMaker::one_line(cleaned)
+		code
 	}
 }

tests/valid/struct_from_json.test.w

@@ -263,9 +263,15 @@ bring "./subdir/structs_2.w" as otherExternalStructs;
 
 enum Color { red, green, blue }
 
+/// MyStruct docs
+/// @foo bar
 struct MyStruct {
+  /// m1 docs
   m1: externalStructs.MyStruct;
+  /// m2 docs
   m2: otherExternalStructs.MyStruct;
+  /// color docs
+  /// @example Color.red
   color: Color;
 }
 
@@ -288,7 +294,31 @@ expect.equal(myStruct.color, Color.red);
 let schema = MyStruct.schema();
 schema.validate(jMyStruct); // Should not throw exception
 
-let expectedSchema = {"$id":"/MyStruct","type":"object","properties":{"color":{"type":"string","enum":["red","green","blue"]},"m1":{"type":"object","properties":{"val":{"type":"number"}},"required":["val"]},"m2":{"type":"object","properties":{"val":{"type":"string"}},"required":["val"]}},"required":["color","m1","m2"]};
+let expectedSchema = {
+  "$id": "/MyStruct",
+  "type": "object",
+  "properties": {
+    "color": {
+      "type": "string",
+      "enum": ["red", "green", "blue"],
+      "description": "color docs\n@example Color.red",
+    },
+    "m1": {
+      "type": "object",
+      "properties": { "val": { "type": "number", "description": "val docs" } },
+      "required": ["val"],
+      "description": "m1 docs",
+    },
+    "m2": {
+      "type": "object",
+      "properties": { "val": { "type": "string" } },
+      "required": ["val"],
+      "description": "m2 docs",
+    },
+  },
+  "required": ["color", "m1", "m2"],
+  "description": "MyStruct docs\n@foo bar",
+};
 
 expect.equal(schema.asStr(), Json.stringify(expectedSchema));
 

tests/valid/subdir/structs.w

@@ -1,4 +1,6 @@
+/// MyStruct docs in subdir
 pub struct MyStruct {
+  /// val docs
   val: num;
 }
 

tools/hangar/__snapshots__/test_corpus/valid/optionals.test.w_compile_tf-aws.md

@@ -158,7 +158,7 @@ class $Root extends $stdlib.std.Resource {
     $helpers.nodeof(this).root.$preflightTypesMap = { };
     let $preflightTypesMap = {};
     const cloud = $stdlib.cloud;
-    const Person = $stdlib.std.Struct._createJsonSchema({$id:"/Person",type:"object",properties:{age:{type:"number"},name:{type:"string"},},required:["age","name",]});
+    const Person = $stdlib.std.Struct._createJsonSchema({$id:"/Person",type:"object",properties:{age:{type:"number"},name:{type:"string"},},required:["age","name",],description:""});
     $helpers.nodeof(this).root.$preflightTypesMap = $preflightTypesMap;
     class Super extends $stdlib.std.Resource {
       constructor($scope, $id, ) {

tools/hangar/__snapshots__/test_corpus/valid/parameters/nested/parameters.test.w_compile_tf-aws.md

@@ -36,7 +36,7 @@ class $Root extends $stdlib.std.Resource {
     super($scope, $id);
     $helpers.nodeof(this).root.$preflightTypesMap = { };
     let $preflightTypesMap = {};
-    const MyParams = $stdlib.std.Struct._createJsonSchema({$id:"/MyParams",type:"object",properties:{houses:{type:"array",items:{type:"object",properties:{address:{type:"string"},residents:{type:"array",items:{type:"object",properties:{age:{type:"number"},name:{type:"string"},},required:["age","name",]}},},required:["address","residents",]}},},required:["houses",]});
+    const MyParams = $stdlib.std.Struct._createJsonSchema({$id:"/MyParams",type:"object",properties:{houses:{type:"array",items:{type:"object",properties:{address:{type:"string"},residents:{type:"array",items:{type:"object",properties:{age:{type:"number"},name:{type:"string"},},required:["age","name",],description:""}},},required:["address","residents",],description:""}},},required:["houses",],description:""});
     $helpers.nodeof(this).root.$preflightTypesMap = $preflightTypesMap;
     const myParams = $macros.__Struct_fromJson(false, MyParams, ($helpers.nodeof(this).app.parameters.read({ schema: $macros.__Struct_schema(false, MyParams, ) })));
     $helpers.assert($helpers.eq(myParams.houses.length, 2), "myParams.houses.length == 2");

tools/hangar/__snapshots__/test_corpus/valid/parameters/simple/parameters.test.w_compile_tf-aws.md

@@ -36,7 +36,7 @@ class $Root extends $stdlib.std.Resource {
     super($scope, $id);
     $helpers.nodeof(this).root.$preflightTypesMap = { };
     let $preflightTypesMap = {};
-    const MyParams = $stdlib.std.Struct._createJsonSchema({$id:"/MyParams",type:"object",properties:{foo:{type:"string"},meaningOfLife:{type:"number"},},required:["meaningOfLife",]});
+    const MyParams = $stdlib.std.Struct._createJsonSchema({$id:"/MyParams",type:"object",properties:{foo:{type:"string"},meaningOfLife:{type:"number"},},required:["meaningOfLife",],description:""});
     $helpers.nodeof(this).root.$preflightTypesMap = $preflightTypesMap;
     const myParams = $macros.__Struct_fromJson(false, MyParams, ($helpers.nodeof(this).app.parameters.read({ schema: $macros.__Struct_schema(false, MyParams, ) })));
     {