Whether a declaration is documented is decidable; the sentence is not - #42
Conversation
The second structural rule, and the boundary the documentation research asks about. It refuses a declaration one module offers another -- `pub` or `pub(crate)`, at the top level of a file in `src/` -- with no doc comment above it. Nothing here judges what the comment says. rustc has a lint for this and it says nothing about this crate. `missing_docs` fires on items reachable from the crate root as PUBLIC, and this is a binary: there is no public API, every shared item is `pub(crate)`, and the lint reports zero over twenty-four shared declarations that carry no documentation at all. The compiler is asking about a published surface; the surface a reader of this crate meets is the one between its modules. A list, not a ceiling. The tree does not comply, and "no more than twenty-four" is satisfied by documenting one declaration while adding another, with the gate green through the swap. Naming them means a new one fails -- and a stale entry fails too, the way `policy/hooks.toml` refuses a waiver that matches nothing. That half earned itself immediately: the list was assembled with a regex over the sources first, and the parser found it wrong in BOTH directions -- six shared declarations the regex missed because their signatures wrap, and seven it named that are documented, including a `prevent_unusual_unicode` that exists twice with only one of them bare. Where generation would start, and why it is not here. Selecting the material a writer needs is deterministic and cheap, and the third test prints exactly that bundle -- signature, the module's own docstring, the calling modules -- and generates nothing. What cannot be mechanized is the sentence, because the sentence is the reason the code is that way, which is not in the syntax tree. This repository already refuses the other half from the other side: `no-trivial-comment` reads doc comments too, so a `/// Gets the name.` inserted to satisfy this rule is refused by the content policy on the same commit. The two compose, and neither is a model deciding whether a declaration is adequately documented. The reader moves to `tests/support/syntax.rs`, which is the measurement the structural-tier research wanted: what does the second rule over a syntax tree cost once the first one's reader exists? A predicate and a list. The git-environment rule keeps only what is about git.
|
Warning Review limit reached
Next review available in: 18 minutes You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (4)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #42 +/- ##
=======================================
Coverage 89.44% 89.44%
=======================================
Files 31 31
Lines 9732 9732
=======================================
Hits 8705 8705
Misses 1027 1027 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
2 participants
Answers the documentation deliverable of #13: AST-selected documentation, with generation deliberately outside the pass/fail path.
The rule
Every declaration one module offers another --
puborpub(crate), at the top level of a file insrc/-- has a doc comment above it. Nothing here judges what the comment says.rustc has a lint for this and it says nothing about this crate.
missing_docsfires on items reachable from the crate root as public, and this is a binary: there is no public API, every shared item ispub(crate), and the lint reports zero over twenty-four shared declarations that carry no documentation at all. The compiler is asking about a published surface; the surface a reader of this crate meets is the one between its modules.A list, not a ceiling
The tree does not comply. "No more than twenty-four" is satisfied by documenting one declaration while adding another, with the gate green through the swap, so
KNOWNnames them: a new one fails, and a stale entry fails too -- the waypolicy/hooks.tomlrefuses a waiver that matches nothing.That half earned itself immediately. The list was assembled with a regex over the sources first, and the parser found it wrong in both directions: six shared declarations the regex missed because their signatures wrap, and seven it named that are documented -- including a
prevent_unusual_unicodethat exists twice, with only one of the two bare.Where generation would start, and why it is not here
Selecting the material a writer needs is deterministic and cheap. The third test prints exactly that bundle and generates nothing:
What cannot be mechanized is the sentence, because the sentence is the reason the code is that way, which is not in the syntax tree. This repository already refuses that from the other side:
no-trivial-commentreads doc comments too, so a/// Gets the name.inserted to satisfy this rule is refused by the content policy on the same commit. The two compose, and neither is a model deciding whether a declaration is adequately documented.What the second structural rule cost
The reader moves to
tests/support/syntax.rs. That is the measurement the structural-tier research wanted -- what does a second rule over a syntax tree cost once the first one's reader exists? A predicate and a list. The git-environment test keeps only what is about git, and gains the parse-failure guard by sharing it.Checks
cargo test,cargo clippy --all-targets,cargo fmt --check,uphold scananduphold checkpass locally; the commit went through the installed hooks.