docs(gatsby): improve createPages example (#10777)

<!--
  Have any questions? Check out the contributing docs at https://gatsby.app/contribute, or
  ask in this Pull Request and a Gatsby maintainer will be happy to help :)
-->


<!-- Write a brief description of the changes introduced by this PR -->


<!--
  Link to the issue that is fixed by this PR (if there is one)
  e.g. Fixes #1234, Addresses #1234, Related to #1234, etc.
-->

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

@@ -12,49 +12,49 @@ exports.resolvableExtensions = true
  *
  * See also [the documentation for the action `createPage`](/docs/actions/#createPage).
  * @example
+ * const path = require(`path`)
+ *
  * exports.createPages = ({ graphql, actions }) => {
  *   const { createPage } = actions
- *   return new Promise((resolve, reject) => {
- *     const blogPostTemplate = path.resolve(`src/templates/blog-post.js`)
- *     // Query for markdown nodes to use in creating pages.
- *     resolve(
- *       graphql(
- *         `
- *       {
- *         allMarkdownRemark(limit: 1000) {
- *           edges {
- *             node {
- *               fields {
- *                 slug
- *               }
+ *   const blogPostTemplate = path.resolve(`src/templates/blog-post.js`)
+ *   // Query for markdown nodes to use in creating pages.
+ *   // You can query for whatever data you want to create pages for e.g.
+ *   // products, portfolio items, landing pages, etc.
+ *   return graphql(`
+ *     {
+ *       allMarkdownRemark(limit: 1000) {
+ *         edges {
+ *           node {
+ *             fields {
+ *               slug
  *             }
  *           }
  *         }
  *       }
- *     `
- *       ).then(result => {
- *         if (result.errors) {
- *           reject(result.errors)
- *         }
- *
- *         // Create blog post pages.
- *         result.data.allMarkdownRemark.edges.forEach(edge => {
- *             createPage({
- *               path: `${edge.node.fields.slug}`, // required
- *               component: blogPostTemplate,
- *               context: {
- *                 // Add optional context data. Data can be used as
- *                 // arguments to the page GraphQL query.
- *                 //
- *                 // The page "path" is always available as a GraphQL
- *                 // argument.
- *               },
- *             })
- *         })
+ *     }
+ *   `).then(result => {
+ *     if (result.errors) {
+ *       throw result.errors
+ *     }
  *
- *         return
+ *     // Create blog post pages.
+ *     result.data.allMarkdownRemark.edges.forEach(edge => {
+ *       createPage({
+ *         // Path for this page — required
+ *         path: `${edge.node.fields.slug}`,
+ *         component: blogPostTemplate,
+ *         context: {
+ *           // Add optional context data to be inserted
+ *           // as props into the page component..
+ *           //
+ *           // The context data can also be used as
+ *           // arguments to the page GraphQL query.
+ *           //
+ *           // The page "path" is always available as a GraphQL
+ *           // argument.
+ *         },
  *       })
- *     )
+ *     })
  *   })
  * }
  */