Skip to content

Conversation

@pieh
Copy link
Contributor

@pieh pieh commented Feb 6, 2019

There is some breaking changes here so will require major version bump

Added features:

  • added support for linking typedef/callback to property/param/variable types - this allows defined type once and reusing it in multiple instances
  • added support for members:
    for example
    const object = {
      /**
        * description of static member
        * @type {string}
        */
      thisIsAMember: true
    }
    there are a lot more types of members (i.e class members etc) that are also supported in this PR
  • added support for optional properties:
    /**
     * @property {number} [nameOfOptionalField] desc
     */
    const object
    this was there before but it was tucked in type information making it much harder to use nicely
    this PR sets optional field (true/false) in documentation nodes and moves type information up to not have to handle this in frontend code
    this is BREAKING CHANGE
  • added support for @deprecated field
  • params, properties and returns fields get transformed into separate DocumentationJS nodes - those fields contain subset of DocumentationJS fields, but it's super nice for defining reusable fragments for types (and typedefs)
    this is BREAKING CHANGE if someone was using fragments for those fields - but this might be unlikely anyone actually did because GraphQL type name was generated dynamically during schema inference so it might change between builds, if fragments weren't used there is no need to change anything (i.e. our queries on www don't require any changes)

TODO: bump documentation package version - we are 2 major versions behind latest - from their changelog it doesn't seem like there are any breaking changes that would affect us, but need to validate that

@pieh pieh added status: WIP breaking change If implemented, this proposed work would break functionality for older versions of Gatsby labels Feb 6, 2019
@pieh pieh force-pushed the documentation-js-typedefs branch from 198e531 to 9bb763b Compare February 25, 2019 20:41
@pieh pieh removed the status: WIP label Feb 25, 2019
@pieh pieh changed the title feat(gatsby-transformer-documentationjs): support linking typedefs [wip] feat(gatsby-transformer-documentationjs): support linking typedefs Feb 26, 2019
@pieh pieh merged commit 16b7d0d into gatsbyjs:master Mar 13, 2019
pieh added a commit that referenced this pull request Mar 13, 2019
This includes changes from #11597 which is needed for nested and also some really unrelated changes (to make preview work on netlify). Actual changes for review are limited to pieh/gatsby@58c6855...pieh:www-doc-preview

.org preview available at https://www-doc-preview--tender-curie-facda8.netlify.com/docs/node-api-helpers/

TO-DO before the merge:
 - [x] change new path to `/docs/node-api-helpers` (from `/docs/node-apis-helpers`)
 - [x] remove temporary commit that allow to build previews on netlify ( 58c6855 )
 - [x] merge #11597 and remove commits from that PR from this branch

Closes #4120
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

breaking change If implemented, this proposed work would break functionality for older versions of Gatsby

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant