docs: Update browser and ssr api docs to include pluginOptions parameter (#12547)

## Description

Was using `wrapRootElement` api and had need of `pluginOptions` in my `gatsby-plugin-breadcrumb` plugin.  Documentation didn't show `pluginOptions` as a parameter, but reviewing the code it seems all `Browser` and `SSR` api's do get `pluginOptions` sent as a parameter, from what I can see.  I was able to use them successfully with `wrapRootElement` so thought adding it to the docs would be helpful.

Author: sbardian

packages/gatsby/cache-dir/api-ssr-docs.js

@@ -1,8 +1,13 @@
+/**
+ * Object containing options defined in `gatsby-config.js`
+ * @typedef {object} pluginOptions
+ */
+
 /**
  * Replace the default server renderer. This is useful for integration with
  * Redux, css-in-js libraries, etc. that need custom setups for server
  * rendering.
- * @param {Object} $0
+ * @param {object} $0
  * @param {string} $0.pathname The pathname of the page currently being rendered.
  * @param {function} $0.replaceBodyHTMLString Call this with the HTML string
  * you render. **WARNING** if multiple plugins implement this API it's the
@@ -22,7 +27,7 @@
  * to the `html.js` component.
  * @param {function} $0.setBodyProps Takes an object of data which
  * is merged with other body props and passed to `html.js` as `bodyProps`.
- * @param {Object} pluginOptions
+ * @param {pluginOptions} pluginOptions
  * @example
  * // From gatsby-plugin-glamor
  * const { renderToString } = require("react-dom/server")
@@ -55,7 +60,7 @@ exports.replaceRenderer = true
  * over server rendering. However, if your plugin requires taking over server
  * rendering then that's the one to
  * use
- * @param {Object} $0
+ * @param {object} $0
  * @param {string} $0.pathname The pathname of the page currently being rendered.
  * @param {function} $0.setHeadComponents Takes an array of components as its
  * first argument which are added to the `headComponents` array which is passed
@@ -72,7 +77,7 @@ exports.replaceRenderer = true
  * to the `html.js` component.
  * @param {function} $0.setBodyProps Takes an object of data which
  * is merged with other body props and passed to `html.js` as `bodyProps`.
- * @param {Object} pluginOptions
+ * @param {pluginOptions} pluginOptions
  * @example
  * const { Helmet } = require("react-helmet")
  *
@@ -99,7 +104,7 @@ exports.onRenderBody = true
  * Called after every page Gatsby server renders while building HTML so you can
  * replace head components to be rendered in your `html.js`. This is useful if
  * you need to reorder scripts or styles added by other plugins.
- * @param {Object} $0
+ * @param {object} $0
  * @param {string} $0.pathname The pathname of the page currently being rendered.
  * @param {Array<ReactNode>} $0.getHeadComponents Returns the current `headComponents` array.
  * @param {function} $0.replaceHeadComponents Takes an array of components as its
@@ -116,7 +121,7 @@ exports.onRenderBody = true
  * first argument which replace the `postBodyComponents` array which is passed
  * to the `html.js` component. **WARNING** if multiple plugins implement this
  * API it's the last plugin that "wins".
- * @param {Object} pluginOptions
+ * @param {pluginOptions} pluginOptions
  * @example
  * // Move Typography.js styles to the top of the head section so they're loaded first.
  * exports.onPreRenderHTML = ({ getHeadComponents, replaceHeadComponents }) => {
@@ -144,6 +149,8 @@ exports.onPreRenderHTML = true
  * @param {object} $0
  * @param {ReactNode} $0.element The "Page" React Element built by Gatsby.
  * @param {object} $0.props Props object used by page.
+ * @param {pluginOptions} pluginOptions
+ * @returns {ReactNode} Wrapped element
  * @example
  * import React from "react"
  * import Layout from "./src/components/layout"
@@ -165,6 +172,8 @@ exports.wrapPageElement = true
  * _Note:_ [There is equivalent hook in Browser API](/docs/browser-apis/#wrapRootElement)
  * @param {object} $0
  * @param {ReactNode} $0.element The "Root" React Element built by Gatsby.
+ * @param {pluginOptions} pluginOptions
+ * @returns {ReactNode} Wrapped element
  * @example
  * import React from "react"
  * import { Provider } from "react-redux"

packages/gatsby/src/utils/api-browser-docs.js

@@ -1,5 +1,17 @@
+/**
+ * This argument is empty. This is for consisntency so `pluginOptions` is always second argument.
+ * @typedef {undefined} emptyArg
+ */
+
+/**
+ * Object containing options defined in `gatsby-config.js`
+ * @typedef {object} pluginOptions
+ */
+
 /**
  * Called when the Gatsby browser runtime first starts.
+ * @param {emptyArg} _
+ * @param {pluginOptions} pluginOptions
  * @example
  * exports.onClientEntry = () => {
  *   console.log("We've started!")
@@ -10,6 +22,8 @@ exports.onClientEntry = true
 
 /**
  * Called when the initial (but not subsequent) render of Gatsby App is done on the client.
+ * @param {emptyArg} _
+ * @param {pluginOptions} pluginOptions
  * @example
  * exports.onInitialClientRender = () => {
  *   console.log("ReactDOM.render has executed")
@@ -22,6 +36,7 @@ exports.onInitialClientRender = true
  * @param {object} $0
  * @param {object} $0.location A location object
  * @param {object|null} $0.prevLocation The previous location object
+ * @param {pluginOptions} pluginOptions
  * @example
  * exports.onPreRouteUpdate = ({ location, prevLocation }) => {
  *   console.log("Gatsby started to change location to", location.pathname)
@@ -35,6 +50,7 @@ exports.onPreRouteUpdate = true
  * @param {object} $0
  * @param {object} $0.location A location object
  * @param {object} $0.action The "action" that caused the route change
+ * @param {pluginOptions} pluginOptions
  * @example
  * exports.onRouteUpdateDelayed = () => {
  *   console.log("We can show loading indicator now")
@@ -47,6 +63,7 @@ exports.onRouteUpdateDelayed = true
  * @param {object} $0
  * @param {object} $0.location A location object
  * @param {object|null} $0.prevLocation The previous location object
+ * @param {pluginOptions} pluginOptions
  * @example
  * exports.onRouteUpdate = ({ location, prevLocation }) => {
  *   console.log('new pathname', location.pathname)
@@ -78,6 +95,7 @@ exports.onRouteUpdate = true
  * coordinates to scroll to, a string of the `id` or `name` of an element to
  * scroll to, `false` to not update the scroll position, or `true` for the
  * default behavior.
+ * @param {pluginOptions} pluginOptions
  * @example
  * exports.shouldUpdateScroll = ({
  *   routerProps: { location },
@@ -95,17 +113,22 @@ exports.shouldUpdateScroll = true
 
 /**
  * Allow a plugin to register a Service Worker. Should be a function that returns true.
+ * @param {emptyArg} _
+ * @param {pluginOptions} pluginOptions
+ * @returns {boolean} Should Gatsby register `/sw.js` service worker
  * @example
  * exports.registerServiceWorker = () => true
  */
 exports.registerServiceWorker = true
 
 /**
- * Allow a plugin to replace the page component renderer. This api runner can be used to
- * implement page transitions. See https://github.com/gatsbyjs/gatsby/tree/master/examples/using-page-transitions for an example of this.
+ * Allow a plugin to replace the page component renderer.
+ * @deprecated Use [wrapPageElement](#wrapPageElement) to decorate page element.
  * @param {object} $0
  * @param {object} $0.props The props of the page.
  * @param {object} $0.loader The gatsby loader.
+ * @param {pluginOptions} pluginOptions
+ * @returns {ReactNode} Replaced default page renderer
  */
 exports.replaceComponentRenderer = true
 
@@ -119,6 +142,8 @@ exports.replaceComponentRenderer = true
  * @param {object} $0
  * @param {ReactNode} $0.element The "Page" React Element built by Gatsby.
  * @param {object} $0.props Props object used by page.
+ * @param {pluginOptions} pluginOptions
+ * @returns {ReactNode} Wrapped element
  * @example
  * import React from "react"
  * import Layout from "./src/components/layout"
@@ -140,6 +165,8 @@ exports.wrapPageElement = true
  * _Note:_ [There is equivalent hook in SSR API](/docs/ssr-apis/#wrapRootElement)
  * @param {object} $0
  * @param {ReactNode} $0.element The "Root" React Element built by Gatsby.
+ * @param {pluginOptions} pluginOptions
+ * @returns {ReactNode} Wrapped element
  * @example
  * import React from "react"
  * import { Provider } from "react-redux"
@@ -163,6 +190,7 @@ exports.wrapRootElement = true
  * @param {object} $0
  * @param {string} $0.pathname The pathname whose resources should now be prefetched
  * @param {function} $0.getResourcesForPathname Function for fetching resources related to pathname
+ * @param {pluginOptions} pluginOptions
  */
 exports.onPrefetchPathname = true
 
@@ -172,21 +200,28 @@ exports.onPrefetchPathname = true
  * @param {object} $0
  * @param {string} $0.pathname The pathname whose resources have now been prefetched
  * @param {function} $0.getResourceURLsForPathname Function for fetching URLs for resources related to the pathname
+ * @param {pluginOptions} pluginOptions
  */
 exports.onPostPrefetchPathname = true
 
 /**
  * Plugins can take over prefetching logic. If they do, they should call this
  * to disable the now duplicate core prefetching logic.
+ * @param {emptyArg} _
+ * @param {pluginOptions} pluginOptions
+ * @returns {boolean} Should disable core prefetching
  * @example
  * exports.disableCorePrefetching = () => true
  */
 exports.disableCorePrefetching = true
 
 /**
- * Allow a plugin to replace the ReactDOM.render function call by a custom renderer.
- * This method takes no param and should return a function with same signature as ReactDOM.render()
- * Note it's very important to call the callback after rendering, otherwise Gatsby will not be able to call `onInitialClientRender`
+ * Allow a plugin to replace the `ReactDOM.render`/`ReactDOM.hydrate` function call by a custom renderer.
+ * @param {emptyArg} _
+ * @param {pluginOptions} pluginOptions
+ * @returns {Function} This method should return a function with same signature as `ReactDOM.render()`
+ *
+ * _Note:_ it's very important to call the `callback` after rendering, otherwise Gatsby will not be able to call `onInitialClientRender`
  * @example
  * exports.replaceHydrateFunction = () => {
  *   return (element, container, callback) => {
@@ -201,13 +236,15 @@ exports.replaceHydrateFunction = true
  * Inform plugins when a service worker has been installed.
  * @param {object} $0
  * @param {object} $0.serviceWorker The service worker instance.
+ * @param {pluginOptions} pluginOptions
  */
 exports.onServiceWorkerInstalled = true
 
 /**
  * Inform plugins of when a service worker has an update available.
  * @param {object} $0
  * @param {object} $0.serviceWorker The service worker instance.
+ * @param {pluginOptions} pluginOptions
  */
 exports.onServiceWorkerUpdateFound = true
 
@@ -216,19 +253,22 @@ exports.onServiceWorkerUpdateFound = true
  * and the page is ready to reload to apply changes.
  * @param {object} $0
  * @param {object} $0.serviceWorker The service worker instance.
+ * @param {pluginOptions} pluginOptions
  */
 exports.onServiceWorkerUpdateReady = true
 
 /**
  * Inform plugins when a service worker has become active.
  * @param {object} $0
  * @param {object} $0.serviceWorker The service worker instance.
+ * @param {pluginOptions} pluginOptions
  */
 exports.onServiceWorkerActive = true
 
 /**
  * Inform plugins when a service worker is redundant.
  * @param {object} $0
  * @param {object} $0.serviceWorker The service worker instance.
+ * @param {pluginOptions} pluginOptions
  */
 exports.onServiceWorkerRedundant = true

www/src/components/api-reference/index.js

@@ -46,6 +46,7 @@ export const pageQuery = graphql`
   }
 
   fragment DocumentationFragment on DocumentationJs {
+    kind
     ...DocumentationDescriptionFragment
     ...DocumentationExampleFragment
     ...DocumentationParamsFragment

www/src/components/api-reference/signature.js

@@ -104,7 +104,7 @@ const FunctionSignature = ({ definition, block, ignoreParams }) => {
         .map((param, index) => (
           <React.Fragment key={param.name}>
             {index > 0 && <Punctuation>, </Punctuation>}
-            {param.name}
+            {param.name === `$0` ? `apiCallbackContext` : param.name}
             {param.type && (
               <React.Fragment>
                 <Punctuation>{param.optional && `?`}:</Punctuation>
@@ -125,7 +125,7 @@ const FunctionSignature = ({ definition, block, ignoreParams }) => {
       {definition.returns && definition.returns.length ? (
         <TypeExpression type={definition.returns[0].type} />
       ) : (
-        <TypeComponent>null</TypeComponent>
+        <TypeComponent>undefined</TypeComponent>
       )}
     </Wrapper>
   )

www/src/pages/docs/browser-apis.js

@@ -12,7 +12,9 @@ import { itemListDocs } from "../../utils/sidebar/item-list"
 class BrowserAPIDocs extends React.Component {
   render() {
     const funcs = sortBy(
-      this.props.data.file.childrenDocumentationJs,
+      this.props.data.file.childrenDocumentationJs.filter(
+        doc => doc.kind !== `typedef`
+      ),
       func => func.name
     )
 
@@ -43,7 +45,7 @@ class BrowserAPIDocs extends React.Component {
           <br />
           <hr />
           <h2>Reference</h2>
-          <APIReference docs={funcs} />
+          <APIReference docs={funcs} showTopLevelSignatures={true} />
         </Container>
       </Layout>
     )

www/src/pages/docs/ssr-apis.js

@@ -12,7 +12,9 @@ import { itemListDocs } from "../../utils/sidebar/item-list"
 class SSRAPIs extends React.Component {
   render() {
     const funcs = sortBy(
-      this.props.data.file.childrenDocumentationJs,
+      this.props.data.file.childrenDocumentationJs.filter(
+        doc => doc.kind !== `typedef`
+      ),
       func => func.name
     )
     return (
@@ -42,7 +44,7 @@ class SSRAPIs extends React.Component {
           <br />
           <hr />
           <h2>Reference</h2>
-          <APIReference docs={funcs} />
+          <APIReference docs={funcs} showTopLevelSignatures={true} />
         </Container>
       </Layout>
     )