From 5a17f6a9e9d155ee023bf813460a56596086204c Mon Sep 17 00:00:00 2001
From: Simon Brugman <sfbbrugman@gmail.com>
Date: Mon, 17 Jul 2023 01:35:59 +0200
Subject: [PATCH] pathlib rule docs

---
 .../rules/flake8_use_pathlib/violations.rs    | 48 +++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/crates/ruff/src/rules/flake8_use_pathlib/violations.rs b/crates/ruff/src/rules/flake8_use_pathlib/violations.rs
index 738bffb76d77dd..1595b80fb0a552 100644
--- a/crates/ruff/src/rules/flake8_use_pathlib/violations.rs
+++ b/crates/ruff/src/rules/flake8_use_pathlib/violations.rs
@@ -101,6 +101,30 @@ impl Violation for OsUnlink {
 }
 
 // PTH109
+
+/// ## What is does
+/// Detects the use of `os.getcwd` and `os.getcwdb`.
+///
+/// ## Why is this bad?
+/// `pathlib` offers high-level path manipulations of paths, `os.path` offers low-level manipulation of paths.
+/// Where possible, using `Path` object methods such as `Path.cwd()` improve readability over `os.getcwd()`.
+/// (Exceptions might be in loops where the `Path` object overhead is high.)
+///
+/// ## Examples
+/// ```python
+/// cwd = os.getcwd()
+/// ```
+///
+/// Use instead:
+/// ```python
+/// cwd = Path.cwd()
+/// ```
+///
+/// ## References
+/// * [PEP 428](https://peps.python.org/pep-0428/)
+/// * [Correspondence between `os` and `pathlib`](https://docs.python.org/3/library/pathlib.html#correspondence-to-tools-in-the-os-module)
+/// * [Why you should be using pathlib](https://treyhunner.com/2018/12/why-you-should-be-using-pathlib/)
+/// * [No really, pathlib is great](https://treyhunner.com/2019/01/no-really-pathlib-is-great/)
 #[violation]
 pub struct OsGetcwd;
 
@@ -167,6 +191,30 @@ impl Violation for OsPathIslink {
 }
 
 // PTH115
+
+/// ## What is does
+/// Detects the use of `os.readlink`.
+///
+/// ## Why is this bad?
+/// `pathlib` offers high-level path manipulations of paths, `os.path` offers low-level manipulation of paths.
+/// Where possible, using `Path` object methods such as `Path(x).readlink()` improve readability over `os.readlink(x)`.
+/// (Exceptions might be in loops where the `Path` object overhead is high.)
+///
+/// ## Examples
+/// ```python
+/// link = os.readlink(x)
+/// ```
+///
+/// Use instead:
+/// ```python
+/// link = Path(x).readlink()
+/// ```
+///
+/// ## References
+/// * [PEP 428](https://peps.python.org/pep-0428/)
+/// * [Correspondence between `os` and `pathlib`](https://docs.python.org/3/library/pathlib.html#correspondence-to-tools-in-the-os-module)
+/// * [Why you should be using pathlib](https://treyhunner.com/2018/12/why-you-should-be-using-pathlib/)
+/// * [No really, pathlib is great](https://treyhunner.com/2019/01/no-really-pathlib-is-great/)
 #[violation]
 pub struct OsReadlink;