Doc comments carry internal process identifiers nothing defines
- Dominant language
- Rust
- Stars
- 3
- Forks
- 0
- Avg merge
- 1d 42m
- Merged PRs (30d)
- 11
Description
Doc comments across `rs/` carry parenthetical identifiers of the form `N4.1`, `N4.2`, `N4.6`, as if naming something a reader could look up. Nothing in the repository defines them.
```
git grep -cE '\bN[0-9]+(\.[0-9]+)?\b' -- rs/ # 183 occurrences
git grep -n 'N4\.6' -- . ':!rs/' # no matches
git grep -nE '\bN4\.2\b' -- docs/ '*.md' # no matches
```
They appear in production source, not only in tests — `cyphr-server/src/consistency.rs`, `cyphr-server/src/registration.rs`, `cyphr-storage/src/engine/mod.rs` — and they carry weight in the sentences that use them:
> `/// were supplied -- no standing claim (N4.6). NOT a claim that every`
> `/// Offline verification of equivocation evidence (N4.2).`
> `/// by the key's validity interval [first_seen, revocation) (N4.3).`
**They are not dangling references to a specification that went missing.** They are identifiers from an internal working process — acceptance criteria used while the work was being done — that leaked into shipped doc comments. The notes that define them are working material, not part of this repository, and should not become part of it.
That matters because it rules out the repair a reader would reach for first. **Do not add a glossary.** Importing those definitions would make internal process vocabulary permanent and authoritative in production source, which is worse than the current state: today the identifiers are visibly meaningless to an outsider, and a glossary would make them look like real specification.
The repair is to replace each identifier with the substance it stands for — `(N4.6)` becomes what the criterion actually required — or to delete the parenthetical where the sentence already says it. Every comment then reads on its own to someone holding only this repository, which is the standard the rest of the tree is held to.
Why it is worth doing rather than tolerating: a comment reading `/// no standing claim` is a statement a maintainer can evaluate against the code. The same comment with `(N4.6)` appended implies the behaviour was specified somewhere and is not merely current practice, so it gets treated more cautiously — while supplying nothing to check. The parenthetical adds apparent authority and no information.
The sweep is mechanical to enumerate and bounded:
```
git grep -nE '\bN[0-9]+(\.[0-9]+)?\b' -- rs/
```
This is also mechanically detectable, so a lint forbidding the pattern in tracked source would keep it from recurring once the sweep is done.
Related: a doc comment in `cyphr-server/tests/witness_mode.rs` attributes to an external paper a sentence that does not appear in it, tracked separately. That one is a different failure — a citation whose target is real but whose quotation is not — and the two should not be fixed by the same reflex.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with `git grep -nE '\bN[0-9]+(\.[0-9]+)?\b' -- rs/` and inspect the occurrences in files such as `cyphr-server/src/consistency.rs`, `cyphr-server/src/registration.rs`, and `cyphr-storage/src/engine/mod.rs`. Replace each identifier with its stated substance or remove it when redundant; do not add a glossary. Done means the comments stand on their own and the pattern no longer appears in tracked source, with a lint considered to prevent recurrence.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 58/100