[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
#10377 (review)

## Test Plan

On `invalid_return_type_str.py`.

---------

Co-authored-by: Dhruv Manilawala <dhruvmanila@gmail.com>

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()
+        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

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;
 

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
-   |                ^^^^^ PLE0307
-16 |     
-17 | class Str2:
+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
+18 | 
+19 | # TODO: Once Ruff has better type checking
+   |