Skip to content

Multi-line annotations: JSDoc margins, // comments, trailing commas, precise errors, and inty fmt - #111

Merged
sinelaw merged 2 commits into
mainfrom
claude/confident-dirac-trag9l
Nov 15, 2026
Merged

sinelaw merged 2 commits into
mainfrom
claude/confident-dirac-trag9l

Conversation

@sinelaw

@sinelaw sinelaw commented Nov 15, 2026 •

Copy link
Copy Markdown
Owner

Long /** type … */, /** function … */ and /** const … */ annotations can be written one field, parameter or union member per line, and mean exactly what the one-line form means:

/** type ScoreView = {
 *   id: String,
 *   fitWidth: Number,  // the width the page is laid out for
 *   engraveMs: Number, // how long the last engraving took
 * } */

/** function sideView(
 *   b: Builder,
 *   v: ScoreView,
 *   c: Cached,
 * ) => Undefined */

What changes

  • * margins. On every line after the first, a leading * (optional whitespace, *, optional space) is ignored, as JSDoc does. This applies to type, function, const/let/var and class, with the keyword on the /** line or on the next line. A * that isn't at the start of a line is left alone.
    • When the keyword comes after a margin, the comment counts as an annotation only if it has an annotation's shape and its type parses. Otherwise it stays prose, as on main: /**\n * function foo(bar) is deprecated … and * type Foo = the kind of foo … are still documentation.
  • // comments run to the end of the line inside an annotation and are ignored by the checker. A // inside a string literal type such as "http://" is left alone.
  • Trailing commas are now accepted after the last function parameter, type argument (Map<K, V,>), type parameter (<T,>, type A<T,> =) and tuple element; object fields already allowed one. A union may also start with |.
  • Precise error positions. Each comment body is cleaned with its margins and comments replaced by spaces, so every character stays at its original offset (lexer/doc_annotation.rs). Annotations carry content_start, and the type parser reports errors at the offending name or character on its own line.
  • inty fmt [--check] [--width=N] <file | dir>... rewrites one-line annotations longer than the width (default 100) in that style, with trailing commas.
    • It breaks only lists: records (;-separated fields come out comma-separated), (…) => parameter lists and tuples. It never breaks parenthesised types or index keys. A union goes one member per line only when no member but the last is a function type, because (A) => B | C returns B | C.
    • Before accepting a rewrite, it reads the old and the new comment the way the checker does and parses each type with parse_type_syntax, which reads syntax only: unknown names, with any type arguments, stand for type variables. It keeps the original unless both parse to the same types.
    • It leaves alone short annotations, multi-line annotations, annotations with //, class declarations, multi-declarator vars and all code, so it is idempotent.
    • It keeps a CRLF file's line endings and doesn't follow symlinked directories.
  • Fixes:
    • /**/ is an empty comment again. It used to run on to the next */ and swallow the code in between.
    • /** const a: …, b: … */ no longer splits a declarator at a comma inside a string literal type or after an arrow inside type arguments (Pair<() => A, B>). Both bugs predate this PR and were found by the new property tests.

Behaviour changes to existing code

  • Annotation errors in one-line annotations also point at the culprit now. Four golden expectations were re-blessed for this.
  • /** const a: A, (b) */ is now skipped whole; its leftover text used to be read as code and failed as an unterminated regex.
  • An unterminated /** type … is now an unterminated-comment error instead of being silently accepted.

Review

An independent review agent checked this change. Its confirmed findings are all fixed in the second commit:

  • fmt could produce unparseable output for (A | B)[], index keys, [Symbol.iterator], and unions led by <T> or a where clause.
  • Margin-led prose that passed on main failed to check.
  • The union layout misrepresented a function type's result.

Of its nits, mixed line endings, symlink loops, ;-separated fields and the rank-1 span are fixed. Counting a tab as one column is left as is.

Tests

  • cargo test --workspace passes: 1146 tests, against 1097 on main.
  • crates/inty/tests/multiline_annotations.rs checks every form against its one-line program and checks error positions (line 7, column 16). It also includes the reviewer's prose cases.
  • The same file formats all the repository's JavaScript at widths 40 and 100, checking that the parsed types, idempotence and every program's check result are unchanged.
  • Property tests (format::props), both directions:
    • parse → generate → parse: random annotations (records with optional fields, ;, index keys and [Symbol.iterator]; functions with named and anonymous parameters; unions, tuples, arrays, grouped types and type arguments; string literal types containing commas, brackets and //) are laid out at random widths and indentation, with LF or CRLF. They must read to the same types, formatting again must change nothing, and whenever the layout breaks a too-long annotation the rewrite must be accepted (so the property isn't vacuous).
    • generate → parse → generate: a random type is printed and laid out, read back by the checker's parser, then printed and laid out again. It must be the same type with the same layout.
    • Both pass at 20,000 cases.
  • Also: unit tests for the comment-body cleaning, the formatter and the declarator splitting; the golden 14-multiline-annotation-field; and crates/inty-cli/tests/fmt.rs.

Docs

  • docs/type-system.md has a new section, "Long annotations across lines", covering the recommended style, the prose rule and inty fmt.
  • The README has a short pointer to it.
  • A new CHANGELOG.md has an Unreleased entry.

🤖 Generated with Claude Code

https://claude.ai/code/session_01LCVsboGYRxeSczmLma8JYF

…precise errors, and `inty fmt`

Long `/** type … */`, `/** function … */` and `/** const … */` annotations
can be laid out one field, parameter or union member per line, and mean
exactly what the one-line form means:

    /** type ScoreView = {
     *   id: String,
     *   fitWidth: Number,  // the width the page is laid out for
     * } */

- The scanner reads a statement annotation from the doc comment's body
  with each continuation line's `*` margin and each `//` comment blanked
  to spaces (`lexer/doc_annotation.rs`). Blanking keeps every byte in
  place, so annotations carry `content_start`, the source offset of their
  text, and the type parser reports an error at the offending name or
  character, on its own line, not across the whole comment.
- The keyword may also sit on the line after `/**`; written that way the
  text must have an annotation's shape, so JSDoc prose that starts with
  "function …" or "type …" stays documentation.
- Trailing commas after the last function parameter, type argument, type
  parameter (also in `type A<T,> =`) and tuple element; a union may start
  with `|`.
- `inty fmt [--check] [--width=N] <file | dir>...` rewrites one-line
  annotations longer than the width (default 100) in that style, leaves
  everything else alone, is idempotent, and keeps an annotation only if
  it reads back to the same type text.
- `/**/` is an empty comment again, not the start of a doc comment.

The four golden diagnostics for annotation errors now point at the
culprit. The existing suite passes unchanged otherwise; new tests compare
every multi-line form against its one-line program, check error
positions, and format the repository's JavaScript at widths 40 and 100
checking that every annotation and every program's result is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LCVsboGYRxeSczmLma8JYF
…roperty tests

From an independent review of the multi-line annotation change:

- `inty fmt` could turn a valid annotation into one that no longer parses:
  a trailing comma inside a parenthesised type (`(A | B)[]`) or an index
  key (`[String]: V`, `[Symbol.iterator]: T`), or a union split one member
  per line whose first member was quantified (`<T>(…) => T | Null`). Its
  guard compared text with layout removed, which accepted all of these.
  Now it reads the old and new comment as the checker does and keeps the
  rewrite only if each type parses to the same type
  (`parse_type_syntax`: unknown names, with any type arguments, stand for
  type variables). It also only breaks lists (records, `(…) =>`
  parameters, tuples), and splits a union one per line only when no
  member but the last is a function type, whose result would take in the
  rest (`(A) => B | C`).
- A JSDoc block whose prose after a `*` margin started like an annotation
  (`function foo(bar) is deprecated`, `type Foo = the kind …`,
  `const total: the running total`) became an annotation and failed to
  check. With the keyword after a margin, a comment is now an annotation
  only if its type parses.
- `inty fmt` keeps a CRLF file's line endings, splits `;`-separated
  record fields, and doesn't follow symlinked directories.
- The rank-1 error's span ends at the quantifier's own `>`, not an
  arrow's.

New property tests (`format::props`), both ways round:
- parse → generate → parse: random annotations (records with optional
  fields, `;`, index keys; functions with named and anonymous parameters;
  unions, tuples, arrays, grouped types, type arguments; string literal
  types holding commas, brackets and `//`) laid out at random widths and
  indentation, with LF or CRLF, read to the same types; formatting again
  changes nothing; and whenever the layout breaks a too-long annotation
  the rewrite is taken.
- generate → parse → generate: a random type printed and laid out, read
  back by the checker's parser, prints to the same type and lays out the
  same.

They found two bugs in splitting `/** const a: …, b: … */` declarators,
which predate this branch and are fixed: a comma inside a string literal
type, and an arrow's `>` inside type arguments (`Pair<() => A, B>`)
closing the `<`. Their seeds are checked in.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LCVsboGYRxeSczmLma8JYF
@sinelaw
sinelaw merged commit 276dd1f into main Nov 15, 2026
2 checks passed
@sinelaw
sinelaw deleted the claude/confident-dirac-trag9l branch November 15, 2026 21:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants