How do you document a type or field in GraphQL SDL, and why is a `#` comment not enough?

## Documentation that ships with the contract Most API documentation drifts because it lives somewhere the API does not. GraphQL closes that gap by making documentation part of the type system: a **description** attached to a definition travels with the schema, is readable through introspection, and therefore shows up wherever the schema does — an explorer, generated reference docs, the output of a typed client generator, a registry's schema view. The syntax is deliberately plain. A description is a string literal placed **immediately before** the definition it documents: ```graphql """ A single physical seat on an aircraft. Seats are identified by the number printed on them, such as `14C`, which is unique within one aircraft but not across a fleet. """ type Seat { "The number printed on the seat." number: String! """ Whether the seat may be sold. A blocked seat is still returned so the map keeps its shape; it is blocked for crew rest, a jump seat, or a broken recliner. """ blocked: Boolean! } ``` Position is the whole rule: before, not after, and not inside the braces as a first entry. A string in any other position is either a syntax error or a different construct entirely. ## Where descriptions are allowed Almost everywhere a definition exists: the schema definition itself, object, interface, union, enum, input object and scalar type definitions, field definitions, the arguments of a field, the fields of an input object, individual enum values, and directive definitions. Argument and enum-value descriptions are the ones teams forget and the ones readers most need — `CabinClass.PREMIUM` means something specific to an airline, and the field's own description is the wrong place to explain it. The exception is a **type extension**, which has no description slot in the grammar at all. The type's description belongs with its original definition. Fields declared inside an extension carry their own descriptions normally, so an extending team can document what it added; it just cannot re-document the type. ## Block strings The triple-quoted block string is what descriptions are normally written with, and it has three properties worth knowing: * It spans lines, so a description can have paragraphs. * Common leading whitespace is stripped, so a description indented to match the surrounding SDL does not arrive at a client with four spaces on every line — which would otherwise render as a code block, since contents are Markdown. * No escape sequences are processed inside it except `\"\"\"`, which lets a description contain a literal triple quote. A backslash inside a block string is just a backslash, which is convenient for anything regex-shaped. A single-quoted string is perfectly legal for a one-liner and is common on fields where a sentence is enough. ## Why a comment is not a description `#` starts a comment, and comments are **ignored tokens**: the parser discards them along with commas and whitespace. Nothing downstream ever sees them. So a file full of carefully written `#` notes produces a schema with no documentation at all — the notes help the next person reading the SDL and nobody else. The team that discovers this usually discovers it from a consumer asking what a field means while looking at an explorer that shows an empty description panel, with the answer sitting in the repository three lines above the field. The conversion is mechanical: turn the `#` into quotes and move it, if necessary, so it sits directly before the definition. ## What a description is not It is not a place for deprecation state. A field being deprecated, and the reason for it, are carried by a directive designed for that, and tools treat that state as structured data — they strike the field through, exclude it from suggestions, and count its usage. A sentence in the description saying “don't use this” gets none of that treatment. It is also not free of consequence. A description is part of the published schema, which means it is visible to every consumer that can introspect — internal notes, ticket numbers, and remarks about which downstream system is unreliable do not belong in one. ## In an interview Nobody is turned down for not knowing this, which is exactly why it makes a pleasant question: it separates people who have authored a schema from people who have only consumed one. The complete answer is short — a string before the definition, block strings for anything multi-line, Markdown by specification, readable through introspection, and comments are dropped.