[www] API docs: render return values (#8208)

* Render return values * Support multiple return values * Fix two typos in docs
gatsbyjs · Sep 17, 2018 · dc1e95b · dc1e95b
1 parent 4d26383
commit dc1e95b
Show file tree

Hide file tree

Showing 2 changed files with 52 additions and 4 deletions.
diff --git a/packages/gatsby/src/utils/api-node-docs.js b/packages/gatsby/src/utils/api-node-docs.js
@@ -57,7 +57,6 @@ exports.resolvableExtensions = true
  *     )
  *   })
  * }
- * @returns {Array} array of extensions
  */
 
 exports.createPages = true
@@ -193,8 +192,9 @@ exports.onCreateBabelConfig = true
  * See also the documentation for [`setWebpackConfig`](/docs/actions/#setWebpackConfig).
  *
  * @param {object} $0
- * @param {'develop' | 'develop-html' | 'build-javascript' | 'build-html'} $0.stage The current build stage
- * @param {function(): object} $0.getConfig Returns the current webpack config
+ * @param {string} $0.stage The current build stage. One of 'develop', 'develop-html',
+ * 'build-javascript', or 'build-html'
+ * @param {function} $0.getConfig Returns the current webpack config
  * @param {object} $0.rules A set of preconfigured webpack config rules
  * @param {object} $0.loaders A set of preconfigured webpack config loaders
  * @param {object} $0.plugins A set of preconfigured webpack config plugins

diff --git a/www/src/components/function-list.js b/www/src/components/function-list.js
@@ -80,6 +80,42 @@ export default ({ functions }) => (
             {node.params.map(param => Param(param, 0))}
           </div>
         )}
+        {node.returns &&
+          node.returns.length > 0 && (
+            <div>
+              <h4>Return value</h4>
+              {node.returns.map(ret => (
+                <div
+                  key={`ret ${JSON.stringify(ret)}`}
+                  css={{
+                    marginLeft: `1.05rem`,
+                    ...scale(-1 / 5),
+                    lineHeight: options.baseLineHeight,
+                  }}
+                >
+                  <h5 css={{ margin: 0 }}>
+                    <span css={{ color: `#73725f` }}>
+                      {`{${
+                        ret.type.type === "UnionType"
+                          ? ret.type.elements
+                              .map(el => String(el.name))
+                              .join("|")
+                          : ret.type.name
+                      }}`}
+                    </span>
+                  </h5>
+                  {ret.description && (
+                    <div
+                      css={{ marginBottom: rhythm(-1 / 4) }}
+                      dangerouslySetInnerHTML={{
+                        __html: ret.description.childMarkdownRemark.html,
+                      }}
+                    />
+                  )}
+                </div>
+              ))}
+            </div>
+          )}
 
         {node.examples &&
           node.examples.length > 0 && (
@@ -117,7 +153,19 @@ export const pageQuery = graphql`
       }
     }
     returns {
-      title
+      type {
+        name
+        type
+        elements {
+          name
+          type
+        }
+      }
+      description {
+        childMarkdownRemark {
+          html
+        }
+      }
     }
     examples {
       highlighted