rust-lang / rust-lang/fls

Syntax rules for the first character in outer doc comments

Open
#610 0 comments 0 reactions 0 assignees View on GitHub

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.