Add DTZ002 documentation

crates/ruff/src/rules/flake8_datetimez/rules/call_datetime_today.rs

@@ -8,6 +8,40 @@ use crate::checkers::ast::Checker;
 
 use super::helpers;
 
+/// ## What it does
+/// Checks for usage of `datetime.datetime.today()`.
+///
+/// ## Why is this bad?
+/// `datetime` objects are "naive" by default, in that they do not include
+/// timezone information. "Naive" objects are easy to understand, but ignore
+/// some aspects of reality, which can lead to subtle bugs. Timezone-aware
+/// `datetime` objects are preferred, as they represent a specific moment in
+/// time, unlike "naive" objects.
+///
+/// `datetime.datetime.today()` crates a "naive" object; instead, use
+/// instead, use `datetime.datetime.now(tz=)` to create a timezone-aware
+/// object.
+///
+/// ## Example
+/// ```python
+/// import datetime
+///
+/// datetime.datetime.today()
+/// ```
+///
+/// Use instead:
+/// ```python
+/// import datetime
+///
+/// datetime.datetime.now(tz=datetime.timezone.utc)
+/// ```
+///
+/// Or, for Python 3.11 and later:
+/// ```python
+/// import datetime
+///
+/// datetime.datetime.now(tz=datetime.UTC)
+/// ```
 #[violation]
 pub struct CallDatetimeToday;
 
@@ -21,12 +55,6 @@ impl Violation for CallDatetimeToday {
     }
 }
 
-/// Checks for `datetime.datetime.today()`. (DTZ002)
-///
-/// ## Why is this bad?
-///
-/// It uses the system local timezone.
-/// Use `datetime.datetime.now(tz=)` instead.
 pub(crate) fn call_datetime_today(checker: &mut Checker, func: &Expr, location: TextRange) {
     if !checker
         .semantic()

crates/ruff/src/rules/flake8_datetimez/rules/call_datetime_without_tzinfo.rs

@@ -14,9 +14,12 @@ use super::helpers;
 ///
 /// ## Why is this bad?
 /// `datetime` objects are "naive" by default, in that they do not include
-/// timezone information. By providing a `tzinfo`, a `datetime` can be made
-/// timezone "aware". "Naive" objects are easy to understand, but ignore some
-/// aspects of reality, which can lead to subtle bugs.
+/// timezone information. "Naive" objects are easy to understand, but ignore
+/// some aspects of reality, which can lead to subtle bugs. Timezone-aware
+/// `datetime` objects are preferred, as they represent a specific moment in
+/// time, unlike "naive" objects.
+///
+/// By providing a `tzinfo` value, a `datetime` can be made timezone-aware.
 ///
 /// ## Example
 /// ```python