Skip to content

Keep Doxygen tags off start of continuation line - #1

Merged
jserv merged 1 commit into
mainfrom
doxygen
Aug 16, 2026
Merged

Keep Doxygen tags off start of continuation line#1
jserv merged 1 commit into
mainfrom
doxygen

Conversation

@jserv

@jserv jserv commented Aug 16, 2026

Copy link
Copy Markdown
Contributor

The reflow packer wrapped comment prose without regard for where a Doxygen tag landed. When a tag such as "@PARAM" came to rest as the first word of a continuation line, the next pass read that line as the opening of a kernel-doc region: convert_kernel_doc gates on the first word of a line, so "@PARAM eta theta" turned into "@eta : theta" and the word "param" was gone. Same input, run twice, fewer words. That breaks the no-data-loss rule and the identical-bytes rule at once.

Break one word earlier so the tag lands second instead. That alone is not enough, because when the word moved down is itself a tag the break only relocates the problem; with no such word to move, let the line overflow the column limit. An over-long line is recoverable, a deleted word is not.

is_tag_start covers exactly the words that can trigger the rewrite: any keyword in DOXY_TAGS, which is a superset of the convertible set since doxy_keyword reduces "param[in]" to "param", plus the glued "@name:" kernel-doc form. Claiming every word that opens with "@" or "" was tried and dropped: it wrapped prose such as "\0" early for nothing, and it disagreed with the looks_like_email_or_path guard in classify_lines.


Summary by cubic

Prevents Doxygen and kernel-doc tags from opening continuation lines and freezes standalone one‑sided banners to restore word preservation and one‑pass convergence. Previously, reflow could leave “@PARAM” at column 0 and the next pass rewrote it to kernel‑doc, dropping “param”; it could also split “label ---” so a rerun deleted the rule.

  • Reflow: detects true tag starts (via doxy_keyword/doxy_tag, glued @name:, and looks_like_email_or_path), peels the prior word so a tag never opens a continuation line, overflows only when the prior word is also a tag or when breaking would emit a bare rule, and borrows a word at paragraph end so a rule never stands alone.
  • Banners: adds LineKind::Banner and one_sided_banner; freezes a one‑sided rule line only when it stands alone; single‑line banner blocks bypass normalization; the emitter treats Banner like LabelRow.
  • Parser robustness: grammar() returns an error (assembly has no grammar) and ParserPool propagates it; assembly never panics the parser.
  • CI and tests: run the full check on ubuntu-24.04, macos-15, and windows-2025 with shell: bash; .gitattributes pins * -text to keep fixtures byte‑exact; CLI tests tolerate BrokenPipe on bad‑arg runs; add randomized convergence and focused banner/tag cases; corpus files must be fixed points on the first pass; skip the embedded‑newline path test on non‑Unix.

Written for commit 602cad2. Summary will update on new commits.

Review in cubic

cubic-dev-ai[bot]

This comment was marked as resolved.

@jserv
jserv force-pushed the doxygen branch 2 times, most recently from 12d9351 to 9a19dbf Compare August 16, 2026 13:28
The reflow packer wrapped comment prose without regard for where a
Doxygen tag landed. When a tag such as "@PARAM" came to rest as the
first word of a continuation line, the next pass read that line as the
opening of a kernel-doc region: convert_kernel_doc gates on the first
word of a line, so "@PARAM eta theta" turned into "@eta : theta" and
the word "param" was gone. Same input, run twice, fewer words. That
breaks the no-data-loss rule and the identical-bytes rule at once.

Break one word earlier so the tag lands second instead. That alone is
not enough, because when the word moved down is itself a tag the break
only relocates the problem; with no such word to move, let the line
overflow the column limit. An over-long line is recoverable, a deleted
word is not.

is_tag_start covers exactly the words that can trigger the rewrite: any
keyword in DOXY_TAGS, which is a superset of the convertible set since
doxy_keyword reduces "param[in]" to "param", plus the glued "@name:"
kernel-doc form. Claiming every word that opens with "@" or "\" was
tried and dropped: it wrapped prose such as "\0" early for nothing, and
it disagreed with the looks_like_email_or_path guard in classify_lines.
@jserv
jserv merged commit 490adfa into main Aug 16, 2026
17 checks passed
@jserv
jserv deleted the doxygen branch August 16, 2026 13:51
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.

1 participant