New lint: Puncuate end of sentences.

[i509VCB]

What it does

This lint suggests to end a sentence with punctuation if there is a newline gap, (two \n\n) or the doc comment ends.

Lint Name

puncuate_end_sentence

Category

pedantic

Advantage

• Documentation is made clearer with punctuation at the end of short sentences and long paragraphs.

Drawbacks

• This lint only works for the end of documentation or where a new line gap is present. Otherwise we would have to embed a grammar engine into clippy.
• This lint is not easily applicable in languages that are not descended from Latin (hence the pedantic category).

Example

/// Returns the meaning of life
fn meaning_of_life() -> u32 {
    42
}

Could be written as:

/// Returns the meaning of life.
fn meaning_of_life() -> u32 {
    42
}

[matthiaskrgr]

Do you have a plan how to detect if a line is actually natural language or just code?
https://doc.rust-lang.org/rust-by-example/meta/doc.html

[llogiq]

Also how do you plan to detect

• Sentence fragments (e.g. in lists like this)
• ASCII art diagrams, e.g. ,.-^-.,
• Old school Smileys :-)
• ¿ Espanol?
• abbreviations etc.

?

[i509VCB]

Do you have a plan how to detect if a line is actually natural language or just code? https://doc.rust-lang.org/rust-by-example/meta/doc.html

I could probably rely on the fact code blocks are typically declared inside a code block and avoid checking within a codeblock.

---

Also how do you plan to detect

* Sentence fragments (e.g. in lists like this)

Unsure, will need to think about this.

* ASCII art diagrams, e.g. _,.-^-.,_

This would be a flaw with the end of line detection scheme since needing to end the diagram with a . would ruin the diagram. It's not exactly going to look nice to suppress that specific line from the lint and disabling the entire lint would make errors sneak through.

* Old school Smileys :-)

Probably same answer as ascii art diagrams.

* ¿ Espanol?

This would be a challenge to handle in a language independent way. At least how I understand this, a ¿ must be terminated at the end of a sentence with a ?.

* abbreviations etc.

This is definitely a challenge, as abbreviations can grammatically be correct with or without periods separating each letter.

[MaeIsBad]

For reference here is the implementation of this feature in the godot go linter.
https://github.com/tetafro/godot/blob/9f0a33a7278c1b0746a5c41dfb8ff2344bd73baa/checks.go#L147

It simply checks that the last line in a block of comments ends with any of the following
".", "?", "!", ".)", "?)", "!)", "。", "？", "！", "。）", "？）", "！）"

they are considered valid. There is a bit more code related to skipping go's comment directives, but since rust doesn't use comments for specifying behavior I think that can be ignored.

It also supports providing a regex to make the linter ignore a given line, which would be a nice feature to add here as well