Skip to content

Add descriptions to executable definitions#892

Closed
IvanGoncharov wants to merge 1 commit intomainfrom
executableDescritions
Closed

Add descriptions to executable definitions#892
IvanGoncharov wants to merge 1 commit intomainfrom
executableDescritions

Conversation

@IvanGoncharov
Copy link
Copy Markdown
Member

@IvanGoncharov IvanGoncharov commented Oct 7, 2021 •
edited
Loading

Was already discussed during WG: https://github.com/graphql/graphql-wg/blob/main/notes/2021-04-01.md#adding-descriptions-to-queries-and-fragments-ivan

I prepare a format proposal, here is a couple of key points:

  1. You can add descriptions on operations, fragments, and query variables
  2. You can't add description on the short form of operation only full form.

Example:

"Some description"
query SomeOperation(
  "ID you should provide"
  $id: String
  
  "Switch for experiment ...."
  $enableBaz: Boolean = false,
) {
  foo(id: $id) {
    bar
    baz @include(if: $enableBaz) {
      ...BazInfo
    }
  }
}

"Some description here"
fragment BazInfo on Baz {
  # ...
}

@netlify
Copy link
Copy Markdown

netlify Bot commented Oct 7, 2021 •
edited
Loading

✔️ Deploy Preview for graphql-spec-draft ready!

🔨 Explore the source changes: 14cce61

🔍 Inspect the deploy log: https://app.netlify.com/sites/graphql-spec-draft/deploys/615f262e5946770008f041ee

😎 Browse the preview: https://deploy-preview-892--graphql-spec-draft.netlify.app/draft

@IvanGoncharov
Copy link
Copy Markdown
Member Author

IvanGoncharov commented Oct 7, 2021

It's an incomplete PR at the moment:

  • Need to expand "Descriptions" in Section 2
  • Need to figure out what to do with duplicating "Descriptions" in Section 3

@leebyron leebyron added the 💡 Proposal (RFC 1) RFC Stage 1 (See CONTRIBUTING.md) label Oct 7, 2021
@IvanGoncharov
Copy link
Copy Markdown
Member Author

IvanGoncharov commented Oct 7, 2021

Capturing feedback from WG (suggested by @fotoetienne):
Add a note that descriptions on executable definitions or comments (retroactive change) must not change execution, validation, or response of graphql document. And it is safe to remove comments and descriptions from executable documents.

@michaelstaib michaelstaib mentioned this pull request Nov 3, 2021
Closed
IvanGoncharov added a commit to IvanGoncharov/graphql-js that referenced this pull request Dec 3, 2021
@IvanGoncharov
Add descriptions to executable definitions
95d34e6 
Implements graphql/graphql-spec#892
@IvanGoncharov IvanGoncharov mentioned this pull request Dec 3, 2021
Closed
@IvanGoncharov
Copy link
Copy Markdown
Member Author

IvanGoncharov commented Dec 3, 2021

Implemented in graphql/graphql-js#3402

@benjie benjie mentioned this pull request Oct 9, 2023
Closed
@leebyron leebyron added 📄 Draft (RFC 2) RFC Stage 2 (See CONTRIBUTING.md) and removed 💡 Proposal (RFC 1) RFC Stage 1 (See CONTRIBUTING.md) labels May 15, 2025
@leebyron
Copy link
Copy Markdown
Collaborator

leebyron commented May 15, 2025

@fotoetienne is volunteering to champion this RFC, and we agreed to move this to Draft RFC 2

@martinbonnin
Copy link
Copy Markdown
Contributor

martinbonnin commented May 28, 2025 •
edited
Loading

FWIW, Apollo Kotlin has support for this. We use this to add KDoc to generated types. The description is stripped by the compiler right now but we could keep it if this were to become more widely supported.

@fotoetienne fotoetienne mentioned this pull request Jun 5, 2025
Merged
@martinbonnin
Copy link
Copy Markdown
Contributor

martinbonnin commented Jun 6, 2025

Would it be ok to close this one in favor of #1170?

@glen-84 glen-84 mentioned this pull request Jun 9, 2025
Open
@benjie benjie added the 🌱 Superseded (RFC X) RFC Stage X (See CONTRIBUTING.md) as it has been replaced by a newer proposal label Jun 26, 2025
@benjie
Copy link
Copy Markdown
Member

benjie commented Jun 26, 2025

Superseded by #1170

@benjie benjie closed this Jun 26, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

1 more reviewer

@BoD BoD BoD approved these changes

Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

📄 Draft (RFC 2) RFC Stage 2 (See CONTRIBUTING.md) 🌱 Superseded (RFC X) RFC Stage X (See CONTRIBUTING.md) as it has been replaced by a newer proposal

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

5 participants

@IvanGoncharov @leebyron @martinbonnin @benjie @BoD