Syntax rules for the first character in outer doc comments
Nobody has claimed this yet.
- Dominant language
- reStructuredText
- Stars
- 497
- Forks
- 41
- Avg merge
- 3h 52m
- Merged PRs (30d)
- 4
Description
§2.5 (fls_q8l2jza7d9xa) provides the following syntax rules for outer-doc comments:
OuterBlockDoc ::=
/** (~[*] | BlockCommentOrDoc) (BlockCommentOrDoc | ~[*/ \r])* */
OuterLineDoc ::=
/// (~[/] ~[\n \r]*)?
The ~[*] and ~[/] expressions are there to say that /*** ... */ and //// ... aren't doc comments.
But those expressions match too broadly: they accept LF and CR, which they shouldn't (the notation ~[X] is defined in §1.1.4:14 (fls_blvsfqeevosr) and means to match a single character other than X).
That means that the syntax rules say, for example, that the following input is a single OuterLineDoc:
///
x = 1
Similarly the syntax rules say /**␍ */ (where ␍ represents a CR control character) is accepted as an OuterBlockDoc, although a CR in any other position inside the comment would mean the input wasn't accepted.
The Reference has equivalent syntax rules, so it has the same bug.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the outer-doc syntax rules in §2.5 and the equivalent rules in the Reference. Check the first-character exclusions for LF and CR, then update both rule sets so those characters are not accepted there while preserving valid outer comments.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100