fix: exempt doc comments from the code-comment budget
Rustdoc, JSDoc, NatSpec and docstrings document a surface for callers and are read by tooling — NatSpec ends up in contract metadata. The rule read as an instruction to delete them, and the linter blocked a legitimate rustdoc block. Also: plain block comment bodies were never linted (no per-line marker), and a literal double-star in a code span was flagged as bold. Merges the landmine and MUST categories, which said the same thing.
This commit is contained in:
@@ -8,10 +8,10 @@ paths:
|
||||
Budget: 1-3 lines. Write one only when an agent with the repo and thirty
|
||||
seconds of grep would still get it wrong. That means one of:
|
||||
|
||||
- a landmine no test catches
|
||||
- something that breaks silently — no test catches it, or a caller can
|
||||
break it from outside
|
||||
- a fact not in the repo (deployed bytecode, chain quirk, library bug)
|
||||
- a unit or epoch the type cannot carry (wei, ms, 18-dp)
|
||||
- a MUST or MUST NOT a caller can break
|
||||
|
||||
Good:
|
||||
|
||||
@@ -22,3 +22,11 @@ Everything else: delete. Design rationale and rejected alternatives go in
|
||||
MUST / NEVER.
|
||||
|
||||
Deleting a comment is cheap and reversible. When unsure, delete.
|
||||
|
||||
### Doc comments are not this
|
||||
|
||||
Rustdoc `///`, JSDoc `/** */`, Solidity NatSpec `@notice`/`@dev`, Python
|
||||
docstrings: different genre, budget does not apply. They document a surface
|
||||
for callers who cannot see the body, and tooling reads them — NatSpec ends
|
||||
up in contract metadata. Follow the language's convention, and never strip
|
||||
them to satisfy the budget above.
|
||||
|
||||
Reference in New Issue
Block a user