Repository navigation
Document every public item in the cgp crates - #289
Merged
Merged
Conversation
Every public item in the twelve core and extra crates now carries a doc comment, and each crate enables `#![warn(missing_docs)]` so a new item cannot land undocumented. The construct items keep a one- or two-sentence doc that links the website reference page that owns the semantics, and the remaining items get a short line. The long per-item docs that restated the reference pages are replaced by the link, so the two copies cannot drift.
Every public item in the twelve core and extra crates now carries a doc comment, and each crate enables `#![warn(missing_docs)]` so a new item cannot land undocumented. Each construct's doc states what the construct is for in one sentence, taken from its reference page, and links that page for the details. The long per-item docs that restated the reference pages are replaced by the summary and the link, so the two copies cannot drift.
Every public item in the nine macro crates now carries a doc comment, and each crate enables `#![warn(missing_docs)]`. The AST types, parsers, and code-generation helpers describe what they represent, and the generated marker structs get a doc from the macro that emits them. The `export_construct!` and `define_keyword!` macros now emit a doc line, so the structs they generate no longer need an `#[allow(missing_docs)]`.
The five main crates and the three error backends now document every public item and enable `#![warn(missing_docs)]`, so the whole workspace builds with the lint on. The `cgp` README no longer says the per-item docs are still being filled in, because every public item now carries a short doc that links its reference page.
The review found three problems. A few structs kept a second, shorter doc line after their existing doc, so the two read as one paragraph. The doc comments sat after the attributes on 68 items, which is valid but reads backwards. And the README's docs.rs note claimed every item links a reference page, which only the construct items do. The duplicate lines are removed, the doc comments now precede their attributes, and the README says each construct's doc links its page.
soareschen
marked this pull request as ready for review
November 7, 2026 23:35
`DebugError` and `DisplayError` sit behind `cgp-error-extra`'s `alloc` feature, so the default-feature build never compiled them and the lint never saw them. The all-features clippy job does, and it failed on the two undocumented structs.
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.
Overview
[deepseek-v4.1-flash] Every public item in the
cgpworkspace now carries a doc comment, and every crate enables#![warn(missing_docs)], so a new item cannot land undocumented. Each construct's doc states what the construct is for in one sentence, taken from its reference page, and links that page for the details.Motivation
The crates' API docs on docs.rs were sparse, and the
cgpREADME said so. The reference pages already explain each construct, so a brief doc that links the page keeps the two copies from drifting, and the lint keeps the docs from falling behind again.Impact
The long per-item docs that restated the reference pages are replaced by the summary and the link. The lint is enabled on all 29 published crates, and the
export_construct!anddefine_keyword!macros now emit a doc line for the structs they generate, so those need no#[allow(missing_docs)].The
cgpREADME's docs.rs note no longer says the per-item docs are still being filled in. It now says every public item carries a short doc, and each construct's doc links its reference page.cargo docwithRUSTDOCFLAGS="-D warnings"passes for the workspace, and the 702 tests pass.