Repository navigation
Multi-line annotations: JSDoc margins, // comments, trailing commas, precise errors, and inty fmt - #111
Merged
Conversation
…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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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:What changes
*margins. On every line after the first, a leading*(optional whitespace,*, optional space) is ignored, as JSDoc does. This applies totype,function,const/let/varandclass, with the keyword on the/**line or on the next line. A*that isn't at the start of a line is left alone.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.Map<K, V,>), type parameter (<T,>,type A<T,> =) and tuple element; object fields already allowed one. A union may also start with|.lexer/doc_annotation.rs). Annotations carrycontent_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.;-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 | CreturnsB | C.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.//,classdeclarations, multi-declaratorvars and all code, so it is idempotent./**/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
/** const a: A, (b) */is now skipped whole; its leftover text used to be read as code and failed as an unterminated regex./** 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:
fmtcould produce unparseable output for(A | B)[], index keys,[Symbol.iterator], and unions led by<T>or awhereclause.mainfailed to check.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 --workspacepasses: 1146 tests, against 1097 onmain.crates/inty/tests/multiline_annotations.rschecks every form against its one-line program and checks error positions (line 7, column 16). It also includes the reviewer's prose cases.format::props), both directions:;, 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).14-multiline-annotation-field; andcrates/inty-cli/tests/fmt.rs.Docs
docs/type-system.mdhas a new section, "Long annotations across lines", covering the recommended style, the prose rule andinty fmt.CHANGELOG.mdhas an Unreleased entry.🤖 Generated with Claude Code
https://claude.ai/code/session_01LCVsboGYRxeSczmLma8JYF