How do you define descriptions using type definitions?

[petebrowne]

It's not clear how to define type/args descriptions using type definitions - or if it is even possible.

For instance, using vanilla graphql-js:

export const User = new GraphQLObjectType({
  name: 'User',
  description: 'A user with an account.'
  fields: () => ({
    username: {
      type: new GraphQLNonNull(GraphQLString),
      description: 'A unique name for the user'
    },
  })
});

I expected this to add descriptions, but it doesn't:

export const schema = [`
# A user with an account.
type User {
  # A unique name for the user.
  username: String!
}
`];

[helfer]

@petebrowne I agree 100% that it would be much nicer to have comments turn into descriptions. The reason it doesn't is that we use the parser from graphql-js, and that parser doesn't support it yet. The best way to get it to happen is probably to put your voice behind this PR (or a modified version thereof): graphql/graphql-js#427

[helfer]

And to answer your question on how to do this with graphql-tools currently: you have to pass the descriptions in resolvers like so:

const resolvers = {
  User: {
    __description: "A user with an account",
    username: {
      description: "A unique name for the user",
      resolve: user => user.username,
    }
  }
};

Please note that for types you have to use __description while for fields you just use description.

[petebrowne]

Thanks for the info! I'll follow the graphql-js parser for updates.

[helfer]

@peterbrowne: guess what, descriptions just landed in graphql-js 0.7.0.

[stubailo]

@helfer does graphql-tools support the feature now?

[helfer]

Yep, sure does!

[tonyxiao]

@helfer @stubailo I can't find any docs on how to use the description still. Mind pointing me to the right place?

[stubailo]

Just put a comment in the schema above the relevant field. We don't have docs for it yet.

[tonyxiao]

Hmm that's exactly what I tried though. But doesn't seem to work. I'm using "graphql-tools": "^0.6.6", should be correct?

[DxCx]

Hi @tonyxiao,
Looking at @helfer 's medium post
That is correct (single hashtag)
Are you using graphql-js v 0.7.0?

[tonyxiao]

@DxCx Oh sweet, thanks for the pointer. I assumed that I needed to upgrade graphql-tools, but turns out I actually need to upgrade graphql instead (peerDependency of graphql-tools). Upgraded and working, thanks!

[DxCx]

great @tonyxiao happy to hear it as i didn't had to the time to test it myself, so i assume we can close this issue =)