From 6ea3c178fd0925e609131805fdf34885c68d89a7 Mon Sep 17 00:00:00 2001
From: Konrad Listwan-Ciesielski <konrad.listwan@gmail.com>
Date: Tue, 1 Aug 2023 11:00:50 +0700
Subject: [PATCH] Add DTZ002 documentation (#6146)

## Summary

Adds documentation for DTZ002. Related to
https://github.com/astral-sh/ruff/issues/2646.

## Test Plan

`python scripts/test_docs_formatted.py`
---
 .../rules/call_datetime_today.rs              | 40 ++++++++++++++++---
 .../rules/call_datetime_without_tzinfo.rs     |  9 +++--
 2 files changed, 40 insertions(+), 9 deletions(-)

diff --git a/crates/ruff/src/rules/flake8_datetimez/rules/call_datetime_today.rs b/crates/ruff/src/rules/flake8_datetimez/rules/call_datetime_today.rs
index 684acc6b5a..0528f510ce 100644
--- a/crates/ruff/src/rules/flake8_datetimez/rules/call_datetime_today.rs
+++ b/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()
diff --git a/crates/ruff/src/rules/flake8_datetimez/rules/call_datetime_without_tzinfo.rs b/crates/ruff/src/rules/flake8_datetimez/rules/call_datetime_without_tzinfo.rs
index 8804a1b9ab..885d494e89 100644
--- a/crates/ruff/src/rules/flake8_datetimez/rules/call_datetime_without_tzinfo.rs
+++ b/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