Property :rtype: is redundant

[hoodmane]

Looking at the output, it seems that properties have redundant types. In the test suite, a_property is an example. Defined like:

@property
def a_property(self) -> str:
    """
    Property docstring
    """

The test suite asserts that the type of the property is included in two places. This strikes me as redundant and slightly confusing: does a property really "return" a value? In my opinion, the abstraction makes it look like we are "accessing" the value rather than returning it. To be specific, I want the following change in the output.

     property a_property: str
  
        Property docstring
  
-       Return type:
-          "str"
- 

I applied the following patch to do this:

--- a/src/sphinx_autodoc_typehints/__init__.py
+++ b/src/sphinx_autodoc_typehints/__init__.py
@@ -611,7 +611,7 @@ def _inject_types_to_docstring(
 
                 lines.insert(insert_index, type_annotation)
 
-    if "return" in type_hints and not inspect.isclass(original_obj):
+    if "return" in type_hints and not inspect.isclass(original_obj) and not inspect.isdatadescriptor(original_obj):
         if what == "method" and name.endswith(".__init__"):  # avoid adding a return type for data class __init__
             return
         formatted_annotation = format_annotation(type_hints["return"], app.config)

Do people prefer the current behavior? If some people want the redundant property types, could we add a config option to opt out of it?

[gaborbernat]

Which of these two is used by sphinx?

[hoodmane]

Both appear in rendered sphinx. I'll post a screenshot when I get to a computer.

[hoodmane]

The rst looks like:

   .. py:property:: FetchResponse.status_text
      :module: pyodide.http
      :type: str

      Response status text

      :rtype: str

Which is rendered as:

property status_text: str  <-- from :type: str

    Response status text

    Return type: str      <-- from :rtype: str

I think it looks better with :rtype: str removed and only :type: str included.

With both:

With just the :type: str:

[gaborbernat]

Yeah let's remove the return type here, PR welcome.

[hoodmane]

Great, will do.