Improve description for not documented parameters

[2fd]

Change [NULL] for [NOT DOCUMENTED]

[mlapeyre3]

Hi @2fd,

I am trying to describe arguments for a given query.

This scheme:

# The root query object
type Query {
	# Fetch an Order given its id.
	order(id: ID): Order
}

generates the following:

So now I try:

# The root query object
#
# Arguments
# id: Description of the id argument
type Query {
	# Fetch an Order given its id.
	order(id: ID): Order
}

but it does not work.

I may not be that familiar with the shorthand notation. How can I add a description to an argument? Thanks a lot !

[2fd]

Hello @mlapeyre3 Sorry for the delay. To document a parameter with the IDL place the comment just before You can see an example in the IDL of the mutation and its corresponding documentation

In your case it would remain like this:

# The root query object
type Query {
	# Fetch an Order given its id.
	order(
            # Description of the id argument
            id: ID
        ): Order
}

[mlapeyre3]

Hi @2fd,

Thanks, it works great! I was typing the query order as a single line ... :)

[sp00m]

Could have nice to have this in the doc, I've been looking for it as well ;)

[OlivierCuyp]

@2fd , I was playing around following you examples without success for my use case. I'm using an API gateway which does the schema stitching with micro-services (all in graphql). So I read a bit more on the difference between simple comments and description.

http://facebook.github.io/graphql/June2018/#sec-Descriptions

So I changed from:

# Base user type
type User {
  # User unique id
  id: ID!
  # The full user name
  name: String!
  # The user email address
  email: Email!
}

To:

"Base user type"
type User {
  "Its unique id, which have to be an Int"
  id: ID!
  "The full user name"
  name: String!
  "The user email address"
  email: Email!
}

And that works ! As @sp00m proposed, it would be really nice to have this documented. I can do a PR if you want ...