mirror of
https://github.com/rust-lang/rust.git
synced 2026-05-08 09:38:26 +03:00
Alex Macleod
86e036af36
This introduces a new lint that aims to check for missing terminal punctuation in doc comments. ## Lint scope and motivation It partially addresses https://github.com/rust-lang/rust-clippy/issues/8371 by currently focusing on the case that is both the easiest to look for without advanced NLP capacities and still very useful: missing punctuation at the end of the last sentence of doc comments. This is particularly useful when working in a team to enforce a style guide and make sure all doc comments end with some kind of punctuation, which is often forgotten in the case of short, single-sentence doc comments. The lint is biased towards avoiding false positives so it can be easily adopted without requiring an excessive number of `#[expect]` attributes. It is currently only concerned with Latin languages, but adding support for `。` for instance should be very easy. Even if consistently ending doc comments (even very short ones) with punctuation is somewhat of an opinion, it seems sufficiently well-established, [at least in the `std`](https://github.com/rust-lang/rust/pull/91886), to warrant its own lint, even if of course it would be allow-by-default. ## Lint category and possible evolution Because it is unclear how useful and more complex it would be to also look for missing punctuation at the end of *each* Markdown paragraphs, I opted for the `nursery` category for now. My understanding of [the stability guarantees](https://github.com/rust-lang/rfcs/blob/master/text/2476-clippy-uno.md#stability-guarantees) is that would it not be acceptable to add such capability later if it was part of `pedantic` or `restriction` categories right away. I tried to make sure the lint name allows this kind of iterative evolution. ## Testing I ran the lint against the `core` library which led me to introduce a few special cases (which seem common enough) to avoid false positives: e.g., the last sentence being in parentheses. After excluding specific modules which should likely be excluded (e.g., `core_arch`, `intrinsincs`), it currently finds a bit more than 200 errors in the `core` library. This lint also helped find issues with a few doc comments, which [are now fixed](https://github.com/rust-lang/rust/pull/146136). ## How to review this PR I suppose it is easier to have a look at the UI tests first before checking the implementation. --- *Please write a short comment explaining your change (or "none" for internal only changes)* changelog: add new lint [`doc_paragraphs_missing_punctuation`]