[`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>

crates/ruff_linter/resources/test/fixtures/pylint/invalid_return_type_str.py

@@ -1,12 +1,14 @@
-class Str:
+# These testcases should raise errors
-    def __str__(self):
-        return 1
 
 class Float:
     def __str__(self):
         return 3.05
 
 class Int:
+    def __str__(self):
+        return 1
+
+class Int2:
     def __str__(self):
         return 0
 
@@ -14,15 +16,21 @@ class Bool:
     def __str__(self):
         return False
 
-class Str2:
+# TODO: Once Ruff has better type checking
-    def __str__(self):
-        x = "ruff"
-        return x
-    
-# TODO fixme once Ruff has better type checking
 def return_int():
     return 3
 
 class ComplexReturn:
     def __str__(self):
         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:
+3 | class Float:
-2 |     def __str__(self):
+4 |     def __str__(self):
-3 |         return 1
+5 |         return 3.05
-  |                ^ 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
   |                ^^^^ PLE0307
-8 |     
+6 | 
-9 | class Int:
+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:
+ 7 | class Int:
-10 |     def __str__(self):
+ 8 |     def __str__(self):
-11 |         return 0
+ 9 |         return 1
    |                ^ PLE0307
-12 |     
+10 | 
-13 | class Bool:
+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:
+11 | class Int2:
-14 |     def __str__(self):
+12 |     def __str__(self):
-15 |         return False
+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 |     
+18 | 
-17 | class Str2:
+19 | # TODO: Once Ruff has better type checking
    |
-
-