Docgen improvements (#4757)

* BREAKING CHANGE: make dockets JSON instead of an inferred type * feat(flowTypes): Add flowType info to nodes * fix defaultValue logic
gatsbyjs · Apr 3, 2018 · 409014c · 409014c
1 parent 8ff0414
commit 409014c
Show file tree

Hide file tree

Showing 6 changed files with 70 additions and 6 deletions.
diff --git a/packages/gatsby-transformer-react-docgen/src/Doclets.js b/packages/gatsby-transformer-react-docgen/src/Doclets.js
@@ -1,5 +1,7 @@
 const metadata = require(`react-docgen`)
 
+const DOCLET_PATTERN = /^@(\w+)(?:$|\s((?:[^](?!^@\w))*))/gim
+const { hasOwnProperty: has } = Object.prototype
 let cleanDocletValue = str => {
   str = str.trim()
   if (str.endsWith(`}`) && str.startsWith(`{`)) str = str.slice(1, -1)
@@ -13,7 +15,7 @@ let isLiteral = str => /^('|"|true|false|\d+)/.test(str.trim())
  */
 export const cleanDoclets = desc => {
   desc = desc || ``
-  let idx = desc.indexOf(`@`)
+  let idx = desc.search(DOCLET_PATTERN)
   return (idx === -1 ? desc : desc.substr(0, idx)).trim()
 }
 
@@ -62,11 +64,13 @@ export const applyPropDoclets = prop => {
   if (doclets.required) {
     prop.required = true
   }
-
+  const dft = has.call(doclets, `default`)
+    ? doclets.default
+    : doclets.defaultValue
   // Use @defaultValue to provide a prop's default value
-  if (doclets.defaultValue) {
+  if (dft != null) {
     prop.defaultValue = {
-      value: cleanDocletValue(doclets.defaultValue),
+      value: dft,
       computed: false,
     }
   }

diff --git a/packages/gatsby-transformer-react-docgen/src/__tests__/Doclets.js b/packages/gatsby-transformer-react-docgen/src/__tests__/Doclets.js
@@ -10,6 +10,7 @@ describe(`transformer-react-doc-gen: Doclets`, () => {
       required: true,
     })
   })
+
   it(`should apply @required`, () => {
     const doclets = {
       defaultValue: `() => {}`,
@@ -43,7 +44,7 @@ describe(`transformer-react-doc-gen: Doclets`, () => {
 
   it(`should create a union type for none-literals`, () => {
     const doclets = {
-      type: `(string|func|bool)`,
+      type: `{(string|func|bool)}`,
     }
     expect(applyPropDoclets({ doclets, type: {} })).toEqual({
       doclets,

diff --git a/packages/gatsby-transformer-react-docgen/src/__tests__/fixtures/classes.js b/packages/gatsby-transformer-react-docgen/src/__tests__/fixtures/classes.js
@@ -11,10 +11,18 @@ function Foo() {
   return <div />
 }
 
+/**
+ * Description!
+ *
+ * @alias {MyComponent}
+ */
 class Bar extends React.Component {
   static propTypes = {
     /**
-     * An object hash of field errors for the form.
+     * An object hash of field (fix this @mention?) errors for the form.
+     *
+     * @type {Foo}
+     * @default blue
      */
     objProp: React.PropTypes.object,
 

diff --git a/packages/gatsby-transformer-react-docgen/src/__tests__/fixtures/flow.js b/packages/gatsby-transformer-react-docgen/src/__tests__/fixtures/flow.js
@@ -0,0 +1,23 @@
+// @flow
+import React, { Component } from "react"
+
+type Props = {
+  /** Description of prop "foo". */
+  primitive: number,
+  /** Description of prop "bar". */
+  literalsAndUnion: "string" | "otherstring" | number,
+  arr: Array<any>,
+  func?: (value: string) => void,
+  obj?: { subvalue: ?boolean },
+}
+
+/**
+ * General component description.
+ */
+export default class MyComponent extends Component<void, Props, void> {
+  props: Props
+
+  render(): ?ReactElement {
+    // ...
+  }
+}
diff --git a/packages/gatsby-transformer-react-docgen/src/__tests__/on-node-create.js b/packages/gatsby-transformer-react-docgen/src/__tests__/on-node-create.js
@@ -86,6 +86,19 @@ describe(`transformer-react-doc-gen: onCreateNode`, () => {
     expect(types.ComponentProp).toHaveLength(14)
   })
 
+  it(`should delicately remove doclets`, async () => {
+    await run(node)
+
+    let types = groupBy(createdNodes, `internal.type`)
+    expect(types.ComponentProp[0].description).toEqual(
+      `An object hash of field (fix this @mention?) errors for the form.`
+    )
+    expect(types.ComponentProp[0].doclets).toEqual({
+      type: `{Foo}`,
+      default: `blue`,
+    })
+  })
+
   it(`should extract create description nodes with markdown types`, async () => {
     await run(node)
     let types = groupBy(createdNodes, `internal.type`)
@@ -104,4 +117,16 @@ describe(`transformer-react-doc-gen: onCreateNode`, () => {
 
     expect(!!handler.mock.calls.length).toBe(true)
   })
+
+  describe(`flowTypes`, () => {
+    beforeEach(() => {
+      node.__fixture = `flow.js`
+    })
+    it(`should add flow type info`, async () => {
+      await run(node)
+      expect(createdNodes[1].flowType).toEqual({
+        name: `number`,
+      })
+    })
+  })
 })
diff --git a/packages/gatsby-transformer-react-docgen/src/extend-node-type.js b/packages/gatsby-transformer-react-docgen/src/extend-node-type.js
@@ -67,6 +67,7 @@ const Method = new GraphQLObjectType({
 
 function extendComponents() {
   return {
+    doclets: { type: GraphQLJSON },
     composes: {
       type: new GraphQLList(new GraphQLNonNull(GraphQLString)),
       description: stripIndent`
@@ -90,7 +91,9 @@ function extendComponents() {
 function extendProp() {
   return {
     type: { type: PropTypeValue },
+    flowType: { type: GraphQLJSON },
     defaultValue: { type: PropDefaultValue },
+    doclets: { type: GraphQLJSON },
     docblock: {
       type: GraphQLString,
       description: oneLine`