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

Author: pieh

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"
+  }
 }

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"`;

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(`,`)
+      }
+    }
+  }
+}

packages/gatsby-transformer-documentationjs/src/__tests__/gatsby-node.js

@@ -3,66 +3,267 @@ import path from "path"
 import gatsbyNode from "../gatsby-node"
 
 describe(`transformer-react-doc-gen: onCreateNode`, () => {
-  let actions, node, createdNodes, updatedNodes
-  const createNodeId = jest.fn()
-  createNodeId.mockReturnValue(`uuid-from-gatsby`)
-  let run = (node = node, opts = {}) =>
-    gatsbyNode.onCreateNode(
+  let createdNodes, updatedNodes
+  const createNodeId = jest.fn(id => id)
+  const createContentDigest = jest.fn().mockReturnValue(`content-digest`)
+
+  const node = {
+    id: `node_1`,
+    children: [],
+    absolutePath: path.join(__dirname, `fixtures`, `code.js`),
+    internal: {
+      mediaType: `application/javascript`,
+      type: `File`,
+    },
+  }
+
+  const actions = {
+    createNode: jest.fn(n => createdNodes.push(n)),
+    createParentChildLink: jest.fn(n => {
+      updatedNodes.push(n)
+      const parentNode = createdNodes.find(node => node.id === n.parent.id)
+      if (parentNode) {
+        parentNode.children.push(n.child.id)
+      } else if (n.parent.id !== `node_1`) {
+        throw new Error(`Creating parent-child link for not existing parent`)
+      }
+    }),
+  }
+
+  const run = async (node = node, opts = {}) => {
+    createdNodes = []
+    updatedNodes = []
+    await gatsbyNode.onCreateNode(
       {
         node,
         actions,
         createNodeId,
+        createContentDigest,
       },
       opts
     )
+  }
 
-  beforeEach(() => {
-    createdNodes = []
-    updatedNodes = []
-    node = {
-      id: `node_1`,
-      children: [],
-      absolutePath: path.join(__dirname, `fixtures`, `code.js`),
-      internal: {
-        mediaType: `application/javascript`,
-        type: `File`,
-      },
-    }
-    actions = {
-      createNode: jest.fn(n => createdNodes.push(n)),
-      createParentChildLink: jest.fn(n => updatedNodes.push(n)),
-    }
-  })
-
-  it(`should extract out a description, params, and examples`, async () => {
+  beforeAll(async () => {
     await run(node)
-    expect(createdNodes).toMatchSnapshot()
   })
 
-  it(`should only process javascript File nodes`, async () => {
-    let result
-    result = await run({ internal: { mediaType: `text/x-foo` } })
-    expect(result).toBeNull()
+  describe(`Simple example`, () => {
+    it(`creates doc json apple node`, () => {
+      const appleNode = createdNodes.find(node => node.name === `apple`)
+      expect(appleNode).toBeDefined()
+    })
+
+    it(`should extract out a description, params, and examples`, () => {
+      const appleNode = createdNodes.find(node => node.name === `apple`)
 
-    result = await run({ internal: { mediaType: `application/javascript` } })
-    expect(result).toBeNull()
+      expect(appleNode.examples.length).toBe(1)
+      expect(appleNode.examples[0]).toMatchSnapshot(`example`)
 
-    result = await run({
-      id: `test`,
-      children: [],
-      absolutePath: path.join(__dirname, `fixtures`, `code.js`),
-      internal: { mediaType: `application/javascript`, type: `File` },
+      const appleDescriptionNode = createdNodes.find(
+        node => node.id === appleNode.description___NODE
+      )
+
+      expect(appleDescriptionNode).toBeDefined()
+      expect(appleDescriptionNode.internal.content).toMatchSnapshot(
+        `description content`
+      )
+
+      const paramNode = createdNodes.find(
+        node => node.id === appleNode.params___NODE[0]
+      )
+
+      expect(paramNode).toBeDefined()
+      expect(paramNode.name).toMatchSnapshot(`param name`)
+
+      const paramDescriptionNode = createdNodes.find(
+        node => node.id === paramNode.description___NODE
+      )
+
+      expect(paramDescriptionNode).toBeDefined()
+      expect(paramDescriptionNode.internal.content).toMatchSnapshot(
+        `param description`
+      )
+    })
+
+    it(`should extract code and docs location`, () => {
+      const appleNode = createdNodes.find(node => node.name === `apple`)
+
+      expect(appleNode.docsLocation).toBeDefined()
+      expect(appleNode.docsLocation).toEqual(
+        expect.objectContaining({
+          start: expect.objectContaining({
+            line: 1,
+          }),
+          end: expect.objectContaining({
+            line: 7,
+          }),
+        })
+      )
+
+      expect(appleNode.codeLocation).toBeDefined()
+      expect(appleNode.codeLocation).toEqual(
+        expect.objectContaining({
+          start: expect.objectContaining({
+            line: 8,
+          }),
+          end: expect.objectContaining({
+            line: 10,
+          }),
+        })
+      )
     })
-    expect(createdNodes.length).toBeGreaterThan(0)
   })
 
-  it(`should extract create description nodes with markdown types`, async () => {
-    await run(node)
-    let types = groupBy(createdNodes, `internal.type`)
-    expect(
-      types.DocumentationJSComponentDescription.every(
-        d => d.internal.mediaType === `text/markdown`
+  describe(`Complex example`, () => {
+    let callbackNode, typedefNode
+
+    it(`should create top-level node for callback`, () => {
+      callbackNode = createdNodes.find(
+        node =>
+          node.name === `CallbackType` &&
+          node.kind === `typedef` &&
+          node.parent === `node_1`
       )
-    ).toBe(true)
+      expect(callbackNode).toBeDefined()
+    })
+
+    describe(`should handle typedefs`, () => {
+      it(`should create top-level node for typedef`, () => {
+        typedefNode = createdNodes.find(
+          node =>
+            node.name === `ObjectType` &&
+            node.kind === `typedef` &&
+            node.parent === `node_1`
+        )
+        expect(typedefNode).toBeDefined()
+      })
+
+      let readyNode, nestedNode
+
+      it(`should have property nodes for typedef`, () => {
+        expect(typedefNode.properties___NODE).toBeDefined()
+        expect(typedefNode.properties___NODE.length).toBe(2)
+        ;[readyNode, nestedNode] = typedefNode.properties___NODE.map(paramID =>
+          createdNodes.find(node => node.id === paramID)
+        )
+      })
+
+      it(`should handle type applications`, () => {
+        expect(readyNode).toMatchSnapshot()
+      })
+
+      let nestedFooNode, nestedOptionalNode, nestedCallbackNode
+
+      it(`should have second param as nested object`, () => {
+        expect(nestedNode.name).toBe(`nested`)
+        expect(nestedNode.properties___NODE).toBeDefined()
+        expect(nestedNode.properties___NODE.length).toBe(3)
+        ;[
+          nestedFooNode,
+          nestedOptionalNode,
+          nestedCallbackNode,
+        ] = nestedNode.properties___NODE.map(paramID =>
+          createdNodes.find(node => node.id === paramID)
+        )
+      })
+
+      it(`should strip prefixes from nested nodes`, () => {
+        expect(nestedFooNode.name).not.toContain(`nested`)
+        expect(nestedFooNode.name).toEqual(`foo`)
+      })
+
+      it(`should handle optional types`, () => {
+        expect(nestedOptionalNode.name).toEqual(`optional`)
+        expect(nestedOptionalNode.optional).toEqual(true)
+        expect(nestedOptionalNode.type).toEqual(
+          expect.objectContaining({
+            name: `number`,
+            type: `NameExpression`,
+          })
+        )
+      })
+
+      it(`should handle typedefs in nested properties`, () => {
+        expect(nestedCallbackNode.name).toEqual(`callback`)
+        expect(nestedCallbackNode.optional).toEqual(false)
+        expect(nestedCallbackNode.type).toEqual(
+          expect.objectContaining({
+            name: `CallbackType`,
+            type: `NameExpression`,
+            typeDef___NODE: callbackNode.id,
+          })
+        )
+      })
+    })
+
+    describe(`should handle members`, () => {
+      let complexNode, memberNode
+      beforeAll(() => {
+        complexNode = createdNodes.find(
+          node => node.name === `complex` && node.parent === `node_1`
+        )
+      })
+
+      it(`should create top-level node for complex type`, () => {
+        expect(complexNode).toBeDefined()
+      })
+
+      it(`should have link from complex node to its members`, () => {
+        expect(complexNode.members).toBeDefined()
+        expect(complexNode.members.static___NODE).toBeDefined()
+        expect(complexNode.members.static___NODE.length).toBe(1)
+
+        memberNode = createdNodes.find(
+          node => node.id === complexNode.members.static___NODE[0]
+        )
+        expect(memberNode).toBeDefined()
+        expect(memberNode.parent).toEqual(complexNode.id)
+      })
+
+      it(`should handle type unions`, () => {
+        expect(memberNode.type).toMatchSnapshot()
+      })
+
+      it(`should link to type to type definition`, () => {
+        const typeElement = memberNode.type.elements.find(
+          type => type.name === `ObjectType`
+        )
+        expect(typeElement.typeDef___NODE).toBe(typedefNode.id)
+      })
+    })
+  })
+
+  describe(`Sanity checks`, () => {
+    it(`should extract create description nodes with markdown types`, () => {
+      let types = groupBy(createdNodes, `internal.type`)
+      expect(
+        types.DocumentationJSComponentDescription.every(
+          d => d.internal.mediaType === `text/markdown`
+        )
+      ).toBe(true)
+    })
+
+    it(`creates parent nodes before children`, () => {
+      const seenNodes = []
+      createdNodes.forEach(node => {
+        seenNodes.push(node.id)
+
+        node.children.forEach(childID => {
+          expect(seenNodes.includes(childID)).not.toBe(true)
+        })
+      })
+    })
+
+    it(`should only process javascript File nodes`, async () => {
+      await run({ internal: { mediaType: `text/x-foo` } })
+      expect(createdNodes.length).toBe(0)
+
+      await run({ internal: { mediaType: `application/javascript` } })
+      expect(createdNodes.length).toBe(0)
+
+      await run(node)
+      expect(createdNodes.length).toBeGreaterThan(0)
+    })
   })
 })

packages/gatsby-transformer-documentationjs/src/gatsby-node.js

@@ -1,10 +1,4 @@
 const documentation = require(`documentation`)
-const crypto = require(`crypto`)
-const digest = str =>
-  crypto
-    .createHash(`md5`)
-    .update(str)
-    .digest(`hex`)
 const remark = require(`remark`)
 const _ = require(`lodash`)
 const Prism = require(`prismjs`)
@@ -17,49 +11,35 @@ const stringifyMarkdownAST = (node = ``) => {
   }
 }
 
-const commentId = (parentId, commentNumber) =>
-  `documentationJS ${parentId} comment #${commentNumber}`
+const docId = (parentId, docsJson) =>
+  `documentationJS ${parentId} path #${JSON.stringify(docsJson.path)}`
 const descriptionId = (parentId, name) =>
   `${parentId}--DocumentationJSComponentDescription--${name}`
 
-function createDescriptionNode(
-  node,
-  docNodeId,
-  markdownStr,
-  name,
-  actions,
-  createNodeId
-) {
-  const { createNode } = actions
+function prepareDescriptionNode(node, markdownStr, name, helpers) {
+  const { createNodeId, createContentDigest } = helpers
 
   const descriptionNode = {
-    id: createNodeId(descriptionId(docNodeId, name)),
+    id: createNodeId(descriptionId(node.id, name)),
     parent: node.id,
     children: [],
     internal: {
       type: `DocumentationJSComponentDescription`,
       mediaType: `text/markdown`,
       content: markdownStr,
-      contentDigest: digest(markdownStr),
+      contentDigest: createContentDigest(markdownStr),
     },
   }
 
-  node.children = node.children.concat([descriptionNode.id])
-  createNode(descriptionNode)
-
-  return descriptionNode.id
+  return descriptionNode
 }
 
 /**
  * Implement the onCreateNode API to create documentation.js nodes
  * @param {Object} super this is a super param
  */
-exports.onCreateNode = async ({
-  node,
-  loadNodeContent,
-  actions,
-  createNodeId,
-}) => {
+exports.onCreateNode = async ({ node, actions, ...helpers }) => {
+  const { createNodeId, createContentDigest } = helpers
   const { createNode, createParentChildLink } = actions
 
   if (
@@ -80,76 +60,187 @@ exports.onCreateNode = async ({
   }
 
   if (documentationJson && documentationJson.length > 0) {
-    documentationJson.forEach((docsJson, i) => {
-      const picked = _.pick(docsJson, [`kind`, `memberof`, `name`, `scope`])
-
-      // Defaults
-      picked.params = [{ name: ``, type: { type: ``, name: `` } }]
-      picked.returns = [{ type: { type: ``, name: `` } }]
-      picked.examples = [{ raw: ``, highlighted: `` }]
-
-      // Prepare various sub-pieces.
-      if (docsJson.description) {
-        picked.description___NODE = createDescriptionNode(
-          node,
-          commentId(node.id, i),
-          stringifyMarkdownAST(docsJson.description),
-          `comment.description`,
-          actions,
-          createNodeId
-        )
+    const handledDocs = new WeakMap()
+    const typeDefs = new Map()
+
+    const getNodeIDForType = typeName => {
+      if (typeDefs.has(typeName)) {
+        return typeDefs.get(typeName)
       }
 
-      const transformParam = param => {
-        if (param.description) {
-          param.description___NODE = createDescriptionNode(
-            node,
-            commentId(node.id, i),
-            stringifyMarkdownAST(param.description),
-            param.name,
-            actions,
-            createNodeId
-          )
-          delete param.description
-        }
-        delete param.lineNumber
-
-        // When documenting destructured parameters, the name
-        // is parent.child where we just want the child.
-        if (param.name.split(`.`).length > 1) {
-          param.name = param.name
-            .split(`.`)
-            .slice(-1)
-            .join(`.`)
-        }
+      const index = documentationJson.findIndex(
+        docsJson =>
+          docsJson.name === typeName &&
+          [`typedef`, `constant`].includes(docsJson.kind)
+      )
 
-        if (param.properties) {
-          param.properties = param.properties.map(transformParam)
-        }
+      if (index !== -1) {
+        return prepareNodeForDocs(documentationJson[index], {
+          commentNumber: index,
+        }).node.id
+      }
+
+      return null
+    }
 
-        return param
+    const tryToAddTypeDef = type => {
+      if (type.applications) {
+        type.applications.forEach(tryToAddTypeDef)
       }
 
-      if (docsJson.params) {
-        picked.params = docsJson.params.map(transformParam)
+      if (type.expression) {
+        tryToAddTypeDef(type.expression)
       }
 
-      if (docsJson.returns) {
-        picked.returns = docsJson.returns.map(ret => {
-          if (ret.description) {
-            ret.description___NODE = createDescriptionNode(
-              node,
-              commentId(node.id, i),
-              stringifyMarkdownAST(ret.description),
-              ret.title,
-              actions,
-              createNodeId
-            )
-            delete ret.description
-          }
+      if (type.elements) {
+        type.elements.forEach(tryToAddTypeDef)
+      }
 
-          return ret
-        })
+      if (type.type === `NameExpression` && type.name) {
+        type.typeDef___NODE = getNodeIDForType(type.name)
+      }
+    }
+
+    /**
+     * Prepare Gatsby node from JsDoc object.
+     *  - set description and deprecated fields as markdown
+     *  - recursively process params, properties, returns
+     *  - link types to type definitions
+     *  - unwrap optional types to top level optional field
+     * @param {Object} docsJson JsDoc object. See https://documentation.js.org/html-example/index.json for example of JsDoc objects shape.
+     * @param {Object} args
+     * @param {Number} [args.commentNumber] Index of JsDoc in root of module
+     * @param {Number} args.level Nesting level
+     * @param {string} args.parent Id of parent node
+     */
+    const prepareNodeForDocs = (
+      docsJson,
+      { commentNumber = null, level = 0, parent = node.id } = {}
+    ) => {
+      if (handledDocs.has(docsJson)) {
+        // this was already handled
+        return handledDocs.get(docsJson)
+      }
+
+      const docSkeletonNode = {
+        commentNumber,
+        level,
+        id: createNodeId(docId(node.id, docsJson)),
+        parent,
+        children: [],
+        internal: {
+          type: `DocumentationJs`,
+        },
+      }
+
+      const children = []
+
+      const picked = _.pick(docsJson, [
+        `kind`,
+        `memberof`,
+        `name`,
+        `scope`,
+        `type`,
+        `default`,
+      ])
+
+      picked.optional = false
+      if (docsJson.loc) {
+        // loc is instance of SourceLocation class, and Gatsby doesn't support
+        // class instances at this moment when inferring schema. Serializing
+        // and desirializing converts class instance to plain object.
+        picked.docsLocation = JSON.parse(JSON.stringify(docsJson.loc))
+      }
+      if (docsJson.context && docsJson.context.loc) {
+        picked.codeLocation = JSON.parse(JSON.stringify(docsJson.context.loc))
+      }
+
+      if (picked.type) {
+        if (picked.type.type === `OptionalType` && picked.type.expression) {
+          picked.optional = true
+          picked.type = picked.type.expression
+        }
+
+        tryToAddTypeDef(picked.type)
+      }
+
+      const mdFields = [`description`, `deprecated`]
+
+      mdFields.forEach(fieldName => {
+        if (docsJson[fieldName]) {
+          const childNode = prepareDescriptionNode(
+            docSkeletonNode,
+            stringifyMarkdownAST(docsJson[fieldName]),
+            `comment.${fieldName}`,
+            helpers
+          )
+
+          picked[`${fieldName}___NODE`] = childNode.id
+          children.push({
+            node: childNode,
+          })
+        }
+      })
+
+      const docsSubfields = [`params`, `properties`, `returns`]
+      docsSubfields.forEach(fieldName => {
+        if (docsJson[fieldName] && docsJson[fieldName].length > 0) {
+          picked[`${fieldName}___NODE`] = docsJson[fieldName].map(
+            (docObj, fieldIndex) => {
+              // When documenting destructured parameters, the name
+              // is parent.child where we just want the child.
+              if (docObj.name && docObj.name.split(`.`).length > 1) {
+                docObj.name = docObj.name
+                  .split(`.`)
+                  .slice(-1)
+                  .join(`.`)
+              }
+
+              const adjustedObj = {
+                ...docObj,
+                path: [...docsJson.path, { fieldName, fieldIndex }],
+              }
+
+              const nodeHierarchy = prepareNodeForDocs(adjustedObj, {
+                level: level + 1,
+                parent: docSkeletonNode.id,
+              })
+              children.push(nodeHierarchy)
+              return nodeHierarchy.node.id
+            }
+          )
+        }
+      })
+
+      if (_.isPlainObject(docsJson.members)) {
+        /*
+        docsJson.members = {
+          events: [],
+          global: [],
+          inner: [],
+          instance: [],
+          static: [],
+        }
+        each member type has array of jsdocs in same shape as top level jsdocs
+        so we use same transformation as top level ones
+        */
+        picked.members = _.reduce(
+          docsJson.members,
+          (acc, membersOfType, key) => {
+            if (membersOfType.length > 0) {
+              acc[`${key}___NODE`] = membersOfType.map(member => {
+                const nodeHierarchy = prepareNodeForDocs(member, {
+                  level: level + 1,
+                  parent: docSkeletonNode.id,
+                })
+                children.push(nodeHierarchy)
+                return nodeHierarchy.node.id
+              })
+            }
+            return acc
+          },
+          {}
+        )
       }
 
       if (docsJson.examples) {
@@ -164,22 +255,44 @@ exports.onCreateNode = async ({
         })
       }
 
-      const strContent = JSON.stringify(picked, null, 4)
-
       const docNode = {
+        ...docSkeletonNode,
         ...picked,
-        commentNumber: i,
-        id: createNodeId(commentId(node.id, i)),
-        parent: node.id,
-        children: [],
-        internal: {
-          contentDigest: digest(strContent),
-          type: `DocumentationJs`,
-        },
       }
+      docNode.internal.contentDigest = createContentDigest(docNode)
+
+      if (docNode.kind === `typedef`) {
+        typeDefs.set(docNode.name, docNode.id)
+      }
+
+      const nodeHierarchy = {
+        node: docNode,
+        children,
+      }
+      handledDocs.set(docsJson, nodeHierarchy)
+      return nodeHierarchy
+    }
+
+    const rootNodes = documentationJson.map((docJson, index) =>
+      prepareNodeForDocs(docJson, { commentNumber: index })
+    )
+
+    const createChildrenNodesRecursively = ({ node: parent, children }) => {
+      if (children) {
+        children.forEach(nodeHierarchy => {
+          createNode(nodeHierarchy.node)
+          createParentChildLink({
+            parent,
+            child: nodeHierarchy.node,
+          })
+          createChildrenNodesRecursively(nodeHierarchy)
+        })
+      }
+    }
 
-      createParentChildLink({ parent: node, child: docNode })
-      createNode(docNode)
+    createChildrenNodesRecursively({
+      node,
+      children: rootNodes,
     })
 
     return true