RFC: Descriptions as strings.

[leebyron]

Breaking Change - those using comment descriptions will need to provide {commentDescriptions: true} to the relevant functions

As discussed in graphql/graphql-spec#90

This proposes replacing leading comment blocks as descriptions in the schema definition language with leading strings.

While I think there is some reduced ergonomics of using a string literal instead of a comment to write descriptions (unless perhaps you are accustomed to Python or Clojure), there are some compelling advantages:

• Descriptions are first-class in the AST of the schema definition language.
• Comments can remain "ignored" characters.
• No ambiguity between commented out regions and descriptions.

Specific to this reference implementation, since this is a breaking change and comment descriptions in the experimental SDL have fairly wide usage, I've left the comment description implementation intact and allow it to be enabled via an option. This should help with allowing upgrading with minimal impact on existing codebases and aid in automated transforms.

Note: This PR is dependent on #926 and should not be merged out of order.

[rmosolgo]

Coming from Ruby, comments-as-docs felt very familiar. (In Ruby, comments are all we've got 😆) Folks have been happily using that approach in graphql-ruby for quite a while.

some reduced ergonomics of using a string literal

It seems like the goal here is to simplify the AST, even if it comes at the cost of usability, is that right?

If that's true, what are the benefits of a simpler AST, and who benefits from it? (It was tricky to implement comments-as-descriptions, but now that it's there, we haven't had any trouble with them!)

No ambiguity between commented out regions and descriptions.

I guess this could happen if you commented out one field, right about the other?

type Thing {
  # id: ID!           <- oops?
  name: String!
}

Or are there other spots were people were tripped up by commenting out code?

[stubailo]

I like this a lot precisely for the reasons you mentioned, @leebyron - I think it's an elegant way of not overloading comments to do multiple totally different things, while not expanding the language syntax with totally new symbols or concepts.

[stubailo]

@leebyron do you know when this change will be published? That will be a big breaking change for graphql-tools users since a lot of people are using comments as descriptions, so I'd like to be on top of it.