Question: difference between comments and descriptions?

[tonyghita]

Previous to merging descriptions into the specification, we used comments to document each field and type.

Does the introduction of descriptions deprecate the old functionality of comments? If so, what is the intended usage of comments? If not, what is the difference between comments and descriptions?

[IvanGoncharov]

Does the introduction of descriptions deprecate the old functionality of comments?

@tonyghita Yes it does.

If so, what is the intended usage of comments?

type Person {
  """name of a person"""
  name: String
  #TODO: Add surname

  # FIXME: Commented due to crash
  # avatarUrl: String
}

So comments are completely ignored by GraphQL. They even skipped by parser so it makes them equivalent to whitespaces.

You can read about this change in more details here: graphql/graphql-js#927
If you have time and want to understand the motivation behind this change here is the relevant thread: #90 (comment)

[tonyghita]

Thanks for the clarification and references @IvanGoncharov 👍

[marcospgp]

Time to update the docs with this info :) I can't see it anywhere here: https://graphql.org/learn/schema/#the-query-and-mutation-types

I seem to only be able to find it on unofficial resources. Cheers!

[lorensr]

graphql-tools treats comments (#) as descriptions, in addition to " and """:

"""
comment 1
"""
type Query {
  # comment 2
  hello(
    "comment 3"
    name: String
  ): String
}

Comments can be written in Markdown. Spec section on descriptions: http://spec.graphql.org/draft/#sec-Descriptions