RFC: Descriptions as strings. #927
Conversation
|
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.
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!)
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? |
|
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. |
leebyron
force-pushed
the
rfc-longstring
branch
from
8a229e3
to
7c00820
Compare
leebyron
force-pushed
the
rfc-docstring
branch
4 times, most recently
from
e342105
to
7ff4fe1
Compare
As discussed in graphql/graphql-spec#90 This proposes replacing leading comment blocks as descriptions in the schema definition language with leading strings (typically block 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.
leebyron
force-pushed
the
rfc-docstring
branch
from
7ff4fe1
to
9b0d9ac
Compare
|
@leebyron do you know when this change will be published? That will be a big breaking change for |
- graphql v0.12.0 has a new proposed way of adding field descriptions as strings rather than comments. See graphql/graphql-js#927. This commit adds support for the usecase.
These were added with graphql/graphql-js#927, RFC: Descriptions as strings.
* Add schema printer options These were added with graphql/graphql-js#927, RFC: Descriptions as strings. * Explicitly define allowed printer options
Breaking Change - those using comment descriptions will need to provide
{commentDescriptions: true}to the relevant functionsAs 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:
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.