fix: preserve empty @description (#1177)

vega · Mar 22, 2022 · 32e8948 · 32e8948
1 parent d867c80
commit 32e8948
Show file tree

Hide file tree

Showing 4 changed files with 61 additions and 3 deletions.
diff --git a/src/AnnotationsReader/BasicAnnotationsReader.ts b/src/AnnotationsReader/BasicAnnotationsReader.ts
@@ -85,10 +85,12 @@ export class BasicAnnotationsReader implements AnnotationsReader {
     }
 
     private parseJsDocTag(jsDocTag: ts.JSDocTagInfo): any {
-        // Tags without explicit value (e.g. `@deprecated`) default to `true`.
-        const text = jsDocTag.text?.map((part) => part.text).join("") || "true";
+        const isTextTag = BasicAnnotationsReader.textTags.has(jsDocTag.name);
+        // Non-text tags without explicit value (e.g. `@deprecated`) default to `true`.
+        const defaultText = isTextTag ? "" : "true";
+        const text = jsDocTag.text?.map((part) => part.text).join("") || defaultText;
 
-        if (BasicAnnotationsReader.textTags.has(jsDocTag.name)) {
+        if (isTextTag) {
             return text;
         } else if (BasicAnnotationsReader.jsonTags.has(jsDocTag.name)) {
             return this.parseJson(text) ?? text;

diff --git a/test/valid-data-annotations.test.ts b/test/valid-data-annotations.test.ts
@@ -26,6 +26,10 @@ describe("valid-data-annotations", () => {
         "annotation-deprecated-extended",
         assertValidSchema("annotation-deprecated", "MyObject", "extended", ["deprecationMessage"])
     );
+    it(
+        "annotation-description-override",
+        assertValidSchema("annotation-description-override", "MyObject", "extended", ["markdownDescription"])
+    );
 
     it("annotation-comment", assertValidSchema("annotation-comment", "MyObject", "extended"));
 

diff --git a/test/valid-data/annotation-description-override/main.ts b/test/valid-data/annotation-description-override/main.ts
@@ -0,0 +1,26 @@
+/**
+ * @comment Top level comment
+ */
+export interface MyObject extends Base {
+    /**
+     * @description
+     * @markdownDescription
+     * Use this **field** for:
+     * - show markdown
+     * - show `code`
+     * - show **bold**
+     */
+    field: Base["field"];
+}
+
+interface Base {
+    /**
+     * @description Do not show this message.
+     */
+    field: string;
+
+    /**
+     * Product name.
+     */
+    name: string;
+}
diff --git a/test/valid-data/annotation-description-override/schema.json b/test/valid-data/annotation-description-override/schema.json
@@ -0,0 +1,26 @@
+{
+  "$ref": "#/definitions/MyObject",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "definitions": {
+    "MyObject": {
+      "$comment": "Top level comment",
+      "additionalProperties": false,
+      "properties": {
+        "field": {
+          "description": "",
+          "markdownDescription": "Use this **field** for:\n- show markdown\n- show `code`\n- show **bold**",
+          "type": "string"
+        },
+        "name": {
+          "description": "Product name.",
+          "type": "string"
+        }
+      },
+      "required": [
+        "field",
+        "name"
+      ],
+      "type": "object"
+    }
+  }
+}