feat(gatsby-transformer-documentationjs): support linking typedefs (#…

…11597)
gatsbyjs · Mar 13, 2019 · 16b7d0d · 16b7d0d
1 parent 0fe1148
commit 16b7d0d
Show file tree

Hide file tree

Showing 6 changed files with 1,373 additions and 596 deletions.
diff --git a/packages/gatsby-transformer-documentationjs/package.json b/packages/gatsby-transformer-documentationjs/package.json
@@ -8,7 +8,7 @@
   },
   "dependencies": {
     "@babel/runtime": "^7.0.0",
-    "documentation": "^7.1.0",
+    "documentation": "^9.0.0",
     "prismjs": "^1.14.0"
   },
   "devDependencies": {
@@ -34,6 +34,5 @@
     "build": "babel src --out-dir . --ignore **/__tests__",
     "prepare": "cross-env NODE_ENV=production npm run build",
     "watch": "babel -w src --out-dir . --ignore **/__tests__"
-  },
-  "gitHead": "5bd5aebe066b9875354a81a4b9ed98722731c465"
+  }
 }
diff --git a/packages/gatsby-transformer-documentationjs/src/__tests__/__snapshots__/gatsby-node.js.snap b/packages/gatsby-transformer-documentationjs/src/__tests__/__snapshots__/gatsby-node.js.snap
@@ -1,63 +1,74 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
-exports[`transformer-react-doc-gen: onCreateNode should extract out a description, params, and examples 1`] = `
-Array [
-  Object {
-    "children": Array [],
-    "id": "uuid-from-gatsby",
-    "internal": Object {
-      "content": "A pretty cool jsdoc example
-",
-      "contentDigest": "1effd106a9028bac69276a250a0f96f5",
-      "mediaType": "text/markdown",
-      "type": "DocumentationJSComponentDescription",
+exports[`transformer-react-doc-gen: onCreateNode Complex example should handle members should handle type unions 1`] = `
+Object {
+  "elements": Array [
+    Object {
+      "name": "ObjectType",
+      "type": "NameExpression",
+      "typeDef___NODE": "documentationJS node_1 path #[{\\"name\\":\\"ObjectType\\",\\"kind\\":\\"typedef\\"}]",
     },
-    "parent": "node_1",
-  },
-  Object {
-    "children": Array [],
-    "id": "uuid-from-gatsby",
-    "internal": Object {
-      "content": "A nice crispy apple
-",
-      "contentDigest": "bdc56b714e173673c86ecf5f556c5fd1",
-      "mediaType": "text/markdown",
-      "type": "DocumentationJSComponentDescription",
+    Object {
+      "name": "Object",
+      "type": "NameExpression",
+      "typeDef___NODE": null,
     },
-    "parent": "node_1",
+  ],
+  "type": "UnionType",
+}
+`;
+
+exports[`transformer-react-doc-gen: onCreateNode Complex example should handle typedefs should handle type applications 1`] = `
+Object {
+  "children": Array [
+    "documentationJS node_1 path #[{\\"name\\":\\"ObjectType\\",\\"kind\\":\\"typedef\\"},{\\"fieldName\\":\\"properties\\",\\"fieldIndex\\":0}]--DocumentationJSComponentDescription--comment.description",
+  ],
+  "commentNumber": null,
+  "description___NODE": "documentationJS node_1 path #[{\\"name\\":\\"ObjectType\\",\\"kind\\":\\"typedef\\"},{\\"fieldName\\":\\"properties\\",\\"fieldIndex\\":0}]--DocumentationJSComponentDescription--comment.description",
+  "id": "documentationJS node_1 path #[{\\"name\\":\\"ObjectType\\",\\"kind\\":\\"typedef\\"},{\\"fieldName\\":\\"properties\\",\\"fieldIndex\\":0}]",
+  "internal": Object {
+    "contentDigest": "content-digest",
+    "type": "DocumentationJs",
   },
-  Object {
-    "children": Array [],
-    "commentNumber": 0,
-    "description___NODE": "uuid-from-gatsby",
-    "examples": Array [
+  "level": 1,
+  "name": "ready",
+  "optional": false,
+  "parent": "documentationJS node_1 path #[{\\"name\\":\\"ObjectType\\",\\"kind\\":\\"typedef\\"}]",
+  "type": Object {
+    "applications": Array [
       Object {
-        "highlighted": "<span class=\\"token keyword\\">const</span> apple <span class=\\"token operator\\">=</span> <span class=\\"token function\\">require</span><span class=\\"token punctuation\\">(</span><span class=\\"token string\\">'apple'</span><span class=\\"token punctuation\\">)</span>
-<span class=\\"token function\\">apple</span><span class=\\"token punctuation\\">(</span><span class=\\"token punctuation\\">)</span>",
-        "raw": "const apple = require('apple')
-apple()",
+        "name": "any",
+        "type": "NameExpression",
+        "typeDef___NODE": null,
       },
     ],
-    "id": "uuid-from-gatsby",
-    "internal": Object {
-      "contentDigest": "eb588cf103987de4bb07a2d28a5cf7c5",
-      "type": "DocumentationJs",
+    "expression": Object {
+      "name": "Promise",
+      "type": "NameExpression",
+      "typeDef___NODE": null,
     },
-    "kind": "constant",
-    "name": "apple",
-    "params": Array [
-      Object {
-        "description___NODE": "uuid-from-gatsby",
-        "name": "apple",
-        "title": "param",
-        "type": Object {
-          "name": "string",
-          "type": "NameExpression",
-        },
-      },
-    ],
-    "parent": "node_1",
-    "returns": Array [],
+    "type": "TypeApplication",
   },
-]
+}
 `;
+
+exports[`transformer-react-doc-gen: onCreateNode Simple example should extract out a description, params, and examples: description content 1`] = `
+"A pretty cool jsdoc example
+"
+`;
+
+exports[`transformer-react-doc-gen: onCreateNode Simple example should extract out a description, params, and examples: example 1`] = `
+Object {
+  "highlighted": "<span class=\\"token keyword\\">const</span> apple <span class=\\"token operator\\">=</span> <span class=\\"token function\\">require</span><span class=\\"token punctuation\\">(</span><span class=\\"token string\\">'apple'</span><span class=\\"token punctuation\\">)</span>
+<span class=\\"token function\\">apple</span><span class=\\"token punctuation\\">(</span><span class=\\"token punctuation\\">)</span>",
+  "raw": "const apple = require('apple')
+apple()",
+}
+`;
+
+exports[`transformer-react-doc-gen: onCreateNode Simple example should extract out a description, params, and examples: param description 1`] = `
+"A nice crispy apple
+"
+`;
+
+exports[`transformer-react-doc-gen: onCreateNode Simple example should extract out a description, params, and examples: param name 1`] = `"paramName"`;
diff --git a/packages/gatsby-transformer-documentationjs/src/__tests__/fixtures/code.js b/packages/gatsby-transformer-documentationjs/src/__tests__/fixtures/code.js
@@ -1,10 +1,46 @@
 /**
  * A pretty cool jsdoc example
- * @param {string} apple A nice crispy apple
+ * @param {string} paramName A nice crispy apple
  * @example
  * const apple = require('apple')
  * apple()
  */
-const apple = apple => {
+exports.apple = paramName => {
   console.log(`hi`)
 }
+
+/**
+ * Description of callback type
+ * @callback CallbackType
+ * @param {string} message A message to split
+ * @returns {string[]} Splitted message
+ */
+
+/**
+ * More complex example
+ */
+exports.complex = {
+  /**
+   * Description of object type
+   * @typedef {Object} ObjectType
+   * @property {Promise<any>} ready Returns promise that resolves when instance is ready to use
+   * @property {Object} nested This is nested object
+   * @property {string} nested.foo This is field in nested object
+   * @property {number} [nested.optional] This is optional field in nested object
+   * @property {CallbackType} nested.callback This is function in nested object
+   */
+
+  /**
+   * Description of function
+   * @type {(ObjectType|Object)}
+   */
+  object: {
+    ready: new Promise(),
+    nested: {
+      foo: `bar`,
+      callback: message => { 
+        return message.split(`,`)
+      }
+    }
+  }
+}