Add a way to disable comments as descriptions backcompat

[stubailo]

In [email protected], the preferred way to pass descriptions is with strings, which can now be multiline:

"""
This is a long description
"""
type MyType {
  """
  This can be indented along with the field
   
  Multiple lines here
  """
  field(args: [String]): OtherType
}

We should update examples to encourage this approach over the comment-based one. Also, we should add tests for it to ensure it continues to work the way we expect.

This would go in the docs here: https://www.apollographql.com/docs/graphql-tools/generate-schema.html#descriptions

Also, we should probably add a flag to various functions to disable comments-as-docs, so that people can ensure they have migrated and we can remove that feature in the next major version.

[email2vimalraj]

So if I understand it correctly, it involves the following tasks:

1. Update the doc
2. Add test

3. Also, we should probably add a flag to various functions to disable comments-as-docs, so that people can ensure they have migrated and we can remove that feature in the next major version.

I'm afraid that I understood the point # 3 correctly.

I can start of with the point # 1, if you are fine with it.

[stubailo]

Yeah, starting with (1) is a great idea! I like having the test as well just so we make sure the docs aren't going to break :]

I can write a more detailed description of (3) in a bit, thank you for jumping in!

[email2vimalraj]

@stubailo : FYI, I'm currently working on this. So far, I've updated the docs and currently working on the test part.
It would be great if you can give me some pointer for the (3), so that I can send a single PR if possible.

[stubailo]

Let's do 2 PRs - I think many small PRs is much easier to work with than one big one for me!

For the 3rd, there's this variable around the codebase called backcompatOptions which passes in a flag to turn on comment descriptions. I think we want an option to makeExecutableSchema, mergeSchemas, and maybe other functions I'm forgetting that make sure that backcompat is turned off. So we can say something like:

When using graphql-tools before version X, you used comments to add descriptions to types, fields, and arguments. In the newer versions of the GraphQL specification, you should instead use block strings (...etc...).

To check if you have migrated everything, try adding the disableDocCommentsBackcompat: true flag to makeExecutableSchema. If your app runs, then you've migrated everything correctly! In version 3.0 of graphql-tools this will be the new default.

[email2vimalraj]

I believe this issue shouldn't be closed since there is one more pending to be raised. Can we reopen this?

[stubailo]

Yeah, I think it was automatically closed from the PR being merged :]

[JakeDawkins]

We should see if we can help people transition to the new syntax. How can we detect if something was a comment vs if something is a description?

[orta]

Controversial opinion alert 🔥

What about if graphql-tools keeps the ability to use # for descriptions as an option? I rarely want to write comments on a schema, but always want to add annotations to the types.

E.g. I'd prefer to have lot pages and pages of this:

in comparison to pages of this:

I know it's maintenance for you, but I think a lot of people would be happy setting an option to keep that deprecated style around

[yaacovCR]

I think we can close this. We will track upstream graphql-js and deprecate when they do, preserving flag as long as possible. Upgrade path will be for users to search their schemas for old style comments.