Add Comments to GraphQL Queries

[supernova-at]

GraphQL supports the # character for comments in a GraphQL query.

We should document our queries just like we document our JavaScript functions, including:

• A good semantic name
• The purpose / description of the query
• What each input parameter is

[brendanfalkowski]

As I understood it (and got stung) comments were not supported in GQL unless explicitly enabled because they chose to formalize a string literal @desc instead.

graphql/graphql-js#927

It got me in trouble because IDEs didn't update to reflect the default removal of comments, and that caused the schema to fail validation in some of my early GQL work with PWA Studio.

I'd love to get comments back because it's a pain not being able to comment out code in the schema while trying things out.

I haven't found any standardized format for naming and describing queries (like DocBlock), but I wrote up some of our naming practices here (which is influenced a lot by PWA Studio's schemas): https://manuals.gravitydept.com/code/graphql/schemas

[sirugh]

@magento export issue to JIRA project PWA as Story

[github-jira-sync-bot]

✅ Jira issue https://jira.corp.magento.com/browse/PWA-1759 is successfully created for this GitHub issue.