Sanitize proto comments for rustdoc in generated code#25
Merged
Conversation
Proto-comment passthrough (#7) emits proto source comments as rustdoc `///` lines. Upstream WKT/descriptor proto comments contain markdown that rustdoc misparses: - `[google.protobuf.Duration][]` is treated as a broken intra-doc link and fails under `deny(rustdoc::broken_intra_doc_links)` (4 errors in buffa-types/src/generated/google.protobuf.any.rs). - Bare URLs trigger `rustdoc::bare_urls` (1 warning in buffa-descriptor). - `Option<T>` etc. trigger `rustdoc::invalid_html_tags` (48 warnings in buffa-test). This broke `cargo doc --workspace --no-deps` and would break the docs.rs build on publish. Adds `sanitize_line` in buffa-codegen/src/comments.rs which is applied to prose lines (code blocks left untouched): - Escapes `[`/`]` to `\[`/`\]` unless part of a single-line inline link `[text](url)`. - Wraps bare `http(s)://` URLs in `<...>`. - Escapes `<`/`>` to `\<`/`\>` unless part of an existing `<http(s)://...>` autolink. - Preserves backtick code spans (CommonMark run-length matching). - Passes through already-escaped `\[` etc. Regenerated checked-in WKT and bootstrap descriptor types. Includes drive-by `cargo fmt` for two spots in buffa-codegen that had drifted on main.
asacamano
approved these changes
Apr 1, 2026
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 subscribe to this conversation on GitHub.
Already have an account?
Sign in.
2 participants
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.
Problem
PR #7 added proto-comment passthrough — proto
//comments are emitted as rustdoc///on generated types. Upstream WKT and descriptor proto comments contain markdown that rustdoc misparses:[google.protobuf.Duration][]→ treated as a broken intra-doc link; errors under#.https://…→rustdoc::bare_urlswarning (1 inbuffa-descriptor).Option<T>etc. →rustdoc::invalid_html_tags(48 warnings inbuffa-test).This broke
cargo doc --workspace --no-depsonmainand would break the docs.rs build on publish. Prerequisite for v0.3.0.Fix
Adds
sanitize_lineinbuffa-codegen/src/comments.rs, applied to prose lines only (indented/fenced code blocks are left untouched):[foo]/[foo][]/[foo][bar]\\[foo\\]etc.[text](url)(single-line)https://…<https://…><https://…>Option<T>Option\\<T\\>`code [x]`\\[No new dependencies — hand-rolled byte scanner (all sentinels are ASCII so byte-level comparison is UTF-8-safe). Approach is similar in spirit to prost-build's
sanitize_line, but additionally handles[foo][]collapsed reference links and<T>HTML-tag escaping, which prost handles only via its optionalcleanup-markdown(pulldown-cmark) feature.Known limitation: multi-line markdown links (e.g.
[24-hour linear\nsmear](url)intimestamp.proto) are conservatively escaped — they degrade to literal text plus a clickable autolink. Cosmetic only; preferable to a docs.rs build failure.Verification
cargo doc --workspace --no-deps— clean (0 errors, 0 warnings)task lint— cleantask test— 1390 passed, 0 failedsanitize_lineRegenerated checked-in WKT (
buffa-types/src/generated/) and bootstrap descriptor (buffa-descriptor/src/generated/) types. Also includes drive-bycargo fmtfor two spots inbuffa-codegenthat had drifted onmain.