mirror of
https://github.com/astral-sh/ruff.git
synced 2025-08-03 18:28:24 +00:00
Add flake8-fixme documentation (#5868)
## Summary Completes documentation for the `flake8-fixme` (`FIX`) ruleset. Related to #2646. Tweaks the violation message. For example, ``` FIX001 Line contains FIXME ``` becomes ``` FIX001 Line contains FIXME, consider resolving the issue ``` This is because the previous message was unclear if it was warning against the use of FIXME tags per se, or the code the FIXME tag was annotating. ## Test Plan `cargo test && python scripts/check_docs_formatted.py`
This commit is contained in:
Tom Kuson
GitHub
parent
4bba0bcab8
commit
266e684192
5 changed files with 87 additions and 12 deletions
|
|
@ -3,39 +3,114 @@ use ruff_macros::{derive_message_formats, violation};
|
|||
|
||||
use crate::directives::{TodoComment, TodoDirectiveKind};
|
||||
|
||||
/// ## What it does
|
||||
/// Checks for "TODO" comments.
|
||||
///
|
||||
/// ## Why is this bad?
|
||||
/// "TODO" comments are used to describe an issue that should be resolved
|
||||
/// (usually, a missing feature, optimization, or refactoring opportunity).
|
||||
///
|
||||
/// Consider resolving the issue before deploying the code.
|
||||
///
|
||||
/// Note that if you use "TODO" comments as a form of documentation (e.g.,
|
||||
/// to [provide context for future work](https://gist.github.com/dmnd/ed5d8ef8de2e4cfea174bd5dafcda382)),
|
||||
/// this rule may not be appropriate for your project.
|
||||
///
|
||||
/// ## Example
|
||||
/// ```python
|
||||
/// def greet(name):
|
||||
/// return f"Hello, {name}!" # TODO: Add support for custom greetings.
|
||||
/// ```
|
||||
#[violation]
|
||||
pub struct LineContainsTodo;
|
||||
impl Violation for LineContainsTodo {
|
||||
#[derive_message_formats]
|
||||
fn message(&self) -> String {
|
||||
format!("Line contains TODO")
|
||||
format!("Line contains TODO, consider resolving the issue")
|
||||
}
|
||||
}
|
||||
|
||||
/// ## What it does
|
||||
/// Checks for "FIXME" comments.
|
||||
///
|
||||
/// ## Why is this bad?
|
||||
/// "FIXME" comments are used to describe an issue that should be resolved
|
||||
/// (usually, a bug or unexpected behavior).
|
||||
///
|
||||
/// Consider resolving the issue before deploying the code.
|
||||
///
|
||||
/// Note that if you use "FIXME" comments as a form of documentation, this
|
||||
/// rule may not be appropriate for your project.
|
||||
///
|
||||
/// ## Example
|
||||
/// ```python
|
||||
/// def speed(distance, time):
|
||||
/// return distance / time # FIXME: Raises ZeroDivisionError for time = 0.
|
||||
/// ```
|
||||
#[violation]
|
||||
pub struct LineContainsFixme;
|
||||
impl Violation for LineContainsFixme {
|
||||
#[derive_message_formats]
|
||||
fn message(&self) -> String {
|
||||
format!("Line contains FIXME")
|
||||
format!("Line contains FIXME, consider resolving the issue")
|
||||
}
|
||||
}
|
||||
|
||||
/// ## What it does
|
||||
/// Checks for "XXX" comments.
|
||||
///
|
||||
/// ## Why is this bad?
|
||||
/// "XXX" comments are used to describe an issue that should be resolved.
|
||||
///
|
||||
/// Consider resolving the issue before deploying the code, or, at minimum,
|
||||
/// using a more descriptive comment tag (e.g, "TODO").
|
||||
///
|
||||
/// ## Example
|
||||
/// ```python
|
||||
/// def speed(distance, time):
|
||||
/// return distance / time # XXX: Raises ZeroDivisionError for time = 0.
|
||||
/// ```
|
||||
#[violation]
|
||||
pub struct LineContainsXxx;
|
||||
impl Violation for LineContainsXxx {
|
||||
#[derive_message_formats]
|
||||
fn message(&self) -> String {
|
||||
format!("Line contains XXX")
|
||||
format!("Line contains XXX, consider resolving the issue")
|
||||
}
|
||||
}
|
||||
|
||||
/// ## What it does
|
||||
/// Checks for "HACK" comments.
|
||||
///
|
||||
/// ## Why is this bad?
|
||||
/// "HACK" comments are used to describe an issue that should be resolved
|
||||
/// (usually, a suboptimal solution or temporary workaround).
|
||||
///
|
||||
/// Consider resolving the issue before deploying the code.
|
||||
///
|
||||
/// Note that if you use "TODO" comments as a form of documentation, this
|
||||
/// rule may not be appropriate for your project.
|
||||
///
|
||||
/// ## Example
|
||||
/// ```python
|
||||
/// import os
|
||||
///
|
||||
///
|
||||
/// def running_windows(): # HACK: Use platform module instead.
|
||||
/// try:
|
||||
/// os.mkdir("C:\\Windows\\System32\\")
|
||||
/// except FileExistsError:
|
||||
/// return True
|
||||
/// else:
|
||||
/// os.rmdir("C:\\Windows\\System32\\")
|
||||
/// return False
|
||||
/// ```
|
||||
#[violation]
|
||||
pub struct LineContainsHack;
|
||||
impl Violation for LineContainsHack {
|
||||
#[derive_message_formats]
|
||||
fn message(&self) -> String {
|
||||
format!("Line contains HACK")
|
||||
format!("Line contains HACK, consider resolving the issue")
|
||||
}
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
source: crates/ruff/src/rules/flake8_fixme/mod.rs
|
||||
---
|
||||
T00.py:7:3: FIX001 Line contains FIXME
|
||||
T00.py:7:3: FIX001 Line contains FIXME, consider resolving the issue
|
||||
|
|
||||
5 | # HACK: hack
|
||||
6 | # hack: hack
|
||||
|
|
@ -10,7 +10,7 @@ T00.py:7:3: FIX001 Line contains FIXME
|
|||
8 | # fixme: fixme
|
||||
|
|
||||
|
||||
T00.py:8:3: FIX001 Line contains FIXME
|
||||
T00.py:8:3: FIX001 Line contains FIXME, consider resolving the issue
|
||||
|
|
||||
6 | # hack: hack
|
||||
7 | # FIXME: fixme
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
source: crates/ruff/src/rules/flake8_fixme/mod.rs
|
||||
---
|
||||
T00.py:5:3: FIX004 Line contains HACK
|
||||
T00.py:5:3: FIX004 Line contains HACK, consider resolving the issue
|
||||
|
|
||||
3 | # XXX: xxx
|
||||
4 | # xxx: xxx
|
||||
|
|
@ -11,7 +11,7 @@ T00.py:5:3: FIX004 Line contains HACK
|
|||
7 | # FIXME: fixme
|
||||
|
|
||||
|
||||
T00.py:6:3: FIX004 Line contains HACK
|
||||
T00.py:6:3: FIX004 Line contains HACK, consider resolving the issue
|
||||
|
|
||||
4 | # xxx: xxx
|
||||
5 | # HACK: hack
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
source: crates/ruff/src/rules/flake8_fixme/mod.rs
|
||||
---
|
||||
T00.py:1:3: FIX002 Line contains TODO
|
||||
T00.py:1:3: FIX002 Line contains TODO, consider resolving the issue
|
||||
|
|
||||
1 | # TODO: todo
|
||||
| ^^^^ FIX002
|
||||
|
|
@ -9,7 +9,7 @@ T00.py:1:3: FIX002 Line contains TODO
|
|||
3 | # XXX: xxx
|
||||
|
|
||||
|
||||
T00.py:2:3: FIX002 Line contains TODO
|
||||
T00.py:2:3: FIX002 Line contains TODO, consider resolving the issue
|
||||
|
|
||||
1 | # TODO: todo
|
||||
2 | # todo: todo
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
source: crates/ruff/src/rules/flake8_fixme/mod.rs
|
||||
---
|
||||
T00.py:3:3: FIX003 Line contains XXX
|
||||
T00.py:3:3: FIX003 Line contains XXX, consider resolving the issue
|
||||
|
|
||||
1 | # TODO: todo
|
||||
2 | # todo: todo
|
||||
|
|
@ -11,7 +11,7 @@ T00.py:3:3: FIX003 Line contains XXX
|
|||
5 | # HACK: hack
|
||||
|
|
||||
|
||||
T00.py:4:3: FIX003 Line contains XXX
|
||||
T00.py:4:3: FIX003 Line contains XXX, consider resolving the issue
|
||||
|
|
||||
2 | # todo: todo
|
||||
3 | # XXX: xxx
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue