From f7802ad5dea287f3c853ffaf14a8b2c5dd7daa67 Mon Sep 17 00:00:00 2001
From: boolean <61526956+boolean-light@users.noreply.github.com>
Date: Thu, 14 Mar 2024 13:38:30 +0900
Subject: [PATCH] [`pylint`] Extend docs and test in `invalid-str-return-type`
 (`E307`) (#10400)

## Summary

Added some docs, and a little of test cases in
`invalid-str-return-type`, mentioned in
https://github.com/astral-sh/ruff/pull/10377#pullrequestreview-1934295027

## Test Plan

On `invalid_return_type_str.py`.

---------

Co-authored-by: Dhruv Manilawala <dhruvmanila@gmail.com>
---
 .../pylint/invalid_return_type_str.py         | 34 ++++++-----
 .../rules/pylint/rules/invalid_str_return.rs  | 17 ++++++
 ...s__PLE0307_invalid_return_type_str.py.snap | 58 +++++++++----------
 3 files changed, 66 insertions(+), 43 deletions(-)

diff --git a/crates/ruff_linter/resources/test/fixtures/pylint/invalid_return_type_str.py b/crates/ruff_linter/resources/test/fixtures/pylint/invalid_return_type_str.py
index a47ed1b306..a1eed0ccfa 100644
--- a/crates/ruff_linter/resources/test/fixtures/pylint/invalid_return_type_str.py
+++ b/crates/ruff_linter/resources/test/fixtures/pylint/invalid_return_type_str.py
@@ -1,28 +1,36 @@
-class Str:
-    def __str__(self):
-        return 1
+# These testcases should raise errors
 
 class Float:
     def __str__(self):
         return 3.05
-    
+
 class Int:
+    def __str__(self):
+        return 1
+
+class Int2:
     def __str__(self):
         return 0
-    
+
 class Bool:
     def __str__(self):
         return False
-    
-class Str2:
-    def __str__(self):
-        x = "ruff"
-        return x
-    
-# TODO fixme once Ruff has better type checking
+
+# TODO: Once Ruff has better type checking
 def return_int():
     return 3
 
 class ComplexReturn:
     def __str__(self):
-        return return_int()
\ No newline at end of file
+        return return_int()
+
+# These testcases should NOT raise errors
+
+class Str:
+    def __str__(self):
+        return "ruff"
+
+class Str2:
+    def __str__(self):
+        x = "ruff"
+        return x
diff --git a/crates/ruff_linter/src/rules/pylint/rules/invalid_str_return.rs b/crates/ruff_linter/src/rules/pylint/rules/invalid_str_return.rs
index 00764c4de3..cf7856ecf4 100644
--- a/crates/ruff_linter/src/rules/pylint/rules/invalid_str_return.rs
+++ b/crates/ruff_linter/src/rules/pylint/rules/invalid_str_return.rs
@@ -14,6 +14,23 @@ use crate::checkers::ast::Checker;
 /// ## Why is this bad?
 /// The `__str__` method should return a `str` object. Returning a different
 /// type may cause unexpected behavior.
+///
+/// ## Example
+/// ```python
+/// class Foo:
+///     def __str__(self):
+///         return True
+/// ```
+///
+/// Use instead:
+/// ```python
+/// class Foo:
+///     def __str__(self):
+///         return "Foo"
+/// ```
+///
+/// ## References
+/// - [Python documentation: The `__str__` method](https://docs.python.org/3/reference/datamodel.html#object.__str__)
 #[violation]
 pub struct InvalidStrReturnType;
 
diff --git a/crates/ruff_linter/src/rules/pylint/snapshots/ruff_linter__rules__pylint__tests__PLE0307_invalid_return_type_str.py.snap b/crates/ruff_linter/src/rules/pylint/snapshots/ruff_linter__rules__pylint__tests__PLE0307_invalid_return_type_str.py.snap
index 492aa55038..f7a44c074e 100644
--- a/crates/ruff_linter/src/rules/pylint/snapshots/ruff_linter__rules__pylint__tests__PLE0307_invalid_return_type_str.py.snap
+++ b/crates/ruff_linter/src/rules/pylint/snapshots/ruff_linter__rules__pylint__tests__PLE0307_invalid_return_type_str.py.snap
@@ -1,44 +1,42 @@
 ---
 source: crates/ruff_linter/src/rules/pylint/mod.rs
 ---
-invalid_return_type_str.py:3:16: PLE0307 `__str__` does not return `str`
+invalid_return_type_str.py:5:16: PLE0307 `__str__` does not return `str`
   |
-1 | class Str:
-2 |     def __str__(self):
-3 |         return 1
-  |                ^ PLE0307
-4 | 
-5 | class Float:
-  |
-
-invalid_return_type_str.py:7:16: PLE0307 `__str__` does not return `str`
-  |
-5 | class Float:
-6 |     def __str__(self):
-7 |         return 3.05
+3 | class Float:
+4 |     def __str__(self):
+5 |         return 3.05
   |                ^^^^ PLE0307
-8 |     
-9 | class Int:
+6 | 
+7 | class Int:
   |
 
-invalid_return_type_str.py:11:16: PLE0307 `__str__` does not return `str`
+invalid_return_type_str.py:9:16: PLE0307 `__str__` does not return `str`
    |
- 9 | class Int:
-10 |     def __str__(self):
-11 |         return 0
+ 7 | class Int:
+ 8 |     def __str__(self):
+ 9 |         return 1
    |                ^ PLE0307
-12 |     
-13 | class Bool:
+10 | 
+11 | class Int2:
    |
 
-invalid_return_type_str.py:15:16: PLE0307 `__str__` does not return `str`
+invalid_return_type_str.py:13:16: PLE0307 `__str__` does not return `str`
    |
-13 | class Bool:
-14 |     def __str__(self):
-15 |         return False
+11 | class Int2:
+12 |     def __str__(self):
+13 |         return 0
+   |                ^ PLE0307
+14 | 
+15 | class Bool:
+   |
+
+invalid_return_type_str.py:17:16: PLE0307 `__str__` does not return `str`
+   |
+15 | class Bool:
+16 |     def __str__(self):
+17 |         return False
    |                ^^^^^ PLE0307
-16 |     
-17 | class Str2:
+18 | 
+19 | # TODO: Once Ruff has better type checking
    |
-
-