feat!: allow JSDoc tags without explicit value (e.g. @deprecated) t…

…o default to `true` (#1172)
vega · Mar 21, 2022 · d867c80 · d867c80
1 parent 71fb087
commit d867c80
Show file tree

Hide file tree

Showing 12 changed files with 84 additions and 11 deletions.
diff --git a/src/AnnotationsReader/BasicAnnotationsReader.ts b/src/AnnotationsReader/BasicAnnotationsReader.ts
@@ -85,7 +85,9 @@ export class BasicAnnotationsReader implements AnnotationsReader {
     }
 
     private parseJsDocTag(jsDocTag: ts.JSDocTagInfo): any {
-        const text = (jsDocTag.text ?? []).map((part) => part.text).join("");
+        // Tags without explicit value (e.g. `@deprecated`) default to `true`.
+        const text = jsDocTag.text?.map((part) => part.text).join("") || "true";
+
         if (BasicAnnotationsReader.textTags.has(jsDocTag.name)) {
             return text;
         } else if (BasicAnnotationsReader.jsonTags.has(jsDocTag.name)) {
@@ -97,6 +99,7 @@ export class BasicAnnotationsReader implements AnnotationsReader {
             return undefined;
         }
     }
+
     private parseJson(value: string): any {
         try {
             return json5.parse(value);

diff --git a/test/valid-data-annotations.test.ts b/test/valid-data-annotations.test.ts
@@ -4,6 +4,7 @@ describe("valid-data-annotations", () => {
     it(
         "annotation-custom",
         assertValidSchema("annotation-custom", "MyObject", "basic", [
+            "customBooleanProperty",
             "customNumberProperty",
             "customStringProperty",
             "customComplexProperty",
@@ -18,15 +19,19 @@ describe("valid-data-annotations", () => {
         assertValidSchema("annotation-empty", "MyObject", "extended", ["customEmptyAnnotation"])
     );
     it(
-        "annotation-deprecated-empty-basic",
-        assertValidSchema("annotation-deprecated-empty", "MyObject", "basic", ["customEmptyAnnotation"])
+        "annotation-deprecated-basic",
+        assertValidSchema("annotation-deprecated", "MyObject", "basic", ["deprecationMessage"])
     );
     it(
-        "annotation-deprecated-empty-extended",
-        assertValidSchema("annotation-deprecated-empty", "MyObject", "extended", ["customEmptyAnnotation"])
+        "annotation-deprecated-extended",
+        assertValidSchema("annotation-deprecated", "MyObject", "extended", ["deprecationMessage"])
     );
 
     it("annotation-comment", assertValidSchema("annotation-comment", "MyObject", "extended"));
 
     it("annotation-id", assertValidSchema("annotation-id", "MyObject", "extended", [], "Test"));
+
+    it("annotation-readOnly", assertValidSchema("annotation-readOnly", "MyObject", "basic"));
+
+    it("annotation-writeOnly", assertValidSchema("annotation-writeOnly", "MyObject", "basic"));
 });
diff --git a/test/valid-data/annotation-custom/main.ts b/test/valid-data/annotation-custom/main.ts
@@ -1,4 +1,5 @@
 /**
+ * @customBooleanProperty false
  * @customNumberProperty 14
  * @customStringProperty "string-value"
  * @customComplexProperty { "a": 1, "b": 2 }

diff --git a/test/valid-data/annotation-custom/schema.json b/test/valid-data/annotation-custom/schema.json
@@ -4,6 +4,7 @@
   "definitions": {
     "MyObject": {
       "additionalProperties": false,
+      "customBooleanProperty": false,
       "customComplexProperty": {
         "a": 1,
         "b": 2

diff --git a/test/valid-data/annotation-deprecated-empty/main.ts b/test/valid-data/annotation-deprecated-empty/main.ts
diff --git a/test/valid-data/annotation-deprecated/main.ts b/test/valid-data/annotation-deprecated/main.ts
@@ -0,0 +1,9 @@
+/**
+ * @deprecated
+ * @deprecationMessage Use `NewMyObject` instead.
+ */
+export interface MyObject {
+    one?: string;
+    /** @deprecated */
+    two?: number;
+}
diff --git a/test/valid-data/annotation-deprecated/schema.json b/test/valid-data/annotation-deprecated/schema.json
@@ -0,0 +1,21 @@
+{
+  "$ref": "#/definitions/MyObject",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "definitions": {
+    "MyObject": {
+      "additionalProperties": false,
+      "deprecated": true,
+      "deprecationMessage": "Use `NewMyObject` instead.",
+      "properties": {
+        "one": {
+          "type": "string"
+        },
+        "two": {
+          "deprecated": true,
+          "type": "number"
+        }
+      },
+      "type": "object"
+    }
+  }
+}
diff --git a/test/valid-data/annotation-empty/schema.json b/test/valid-data/annotation-empty/schema.json
@@ -4,7 +4,7 @@
   "definitions": {
     "MyObject": {
       "additionalProperties": false,
-      "customEmptyAnnotation": "",
+      "customEmptyAnnotation": true,
       "type": "object"
     }
   }

diff --git a/test/valid-data/annotation-readOnly/main.ts b/test/valid-data/annotation-readOnly/main.ts
@@ -0,0 +1,5 @@
+export interface MyObject {
+    one?: string;
+    /** @readOnly */
+    two?: number;
+}
diff --git a/...a/annotation-deprecated-empty/schema.json → ...alid-data/annotation-readOnly/schema.json b/...a/annotation-deprecated-empty/schema.json → ...alid-data/annotation-readOnly/schema.json
@@ -4,7 +4,15 @@
   "definitions": {
     "MyObject": {
       "additionalProperties": false,
-      "deprecated": "",
+      "properties": {
+        "one": {
+          "type": "string"
+        },
+        "two": {
+          "readOnly": true,
+          "type": "number"
+        }
+      },
       "type": "object"
     }
   }

diff --git a/test/valid-data/annotation-writeOnly/main.ts b/test/valid-data/annotation-writeOnly/main.ts
@@ -0,0 +1,5 @@
+export interface MyObject {
+    one?: string;
+    /** @writeOnly */
+    two?: number;
+}
diff --git a/test/valid-data/annotation-writeOnly/schema.json b/test/valid-data/annotation-writeOnly/schema.json
@@ -0,0 +1,19 @@
+{
+  "$ref": "#/definitions/MyObject",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "definitions": {
+    "MyObject": {
+      "additionalProperties": false,
+      "properties": {
+        "one": {
+          "type": "string"
+        },
+        "two": {
+          "type": "number",
+          "writeOnly": true
+        }
+      },
+      "type": "object"
+    }
+  }
+}