add option for autodoc to hide undocumented parameters but show undocumented return types

[gschwaer]

Add new option for autodoc_typehints_description_target to include undocumented return values but not undocumented parameters.

Feature or Bugfix

• Feature

Purpose

• Often times return values are obvious (e.g., def parse_int(val: str) -> int) and instead of writing in the docstring :return: the integer it is sufficient to see :rtype: int.
• Currently when one wants to suppress type annotation for undocumented parameters, return type annotation is also disabled (autodoc_typehints_description_target = "documented")
• This PR adds a new config option autodoc_typehints_description_target = "documented_params" that will suppress type annotation for undocumented parameters, but adds type annotations for undocumented return values.

Detail

• An example can be found here.
• The name of the new option might not be ideal ("documented_params") because it does not express that return types are still added. Maybe something link "documented_and_returnvalues" would be better?
• I added a new parameter to augment_descriptions_with_types() to pass the info if the return type should be annotated or not. This could also be solved by passing the config object. Would that be better?
• TODO
  • The new option was not added to the documentation yet.

[tk0miya]

Thank you for your proposal. Nice proposal. I need to know more cases that are difficult to describe the return value. Do you have real examples? It would be helpful for me to imagine how this proposal is worth.

The name of the new option might not be ideal ("documented_params") because it does not express that return types are still added. Maybe something link "documented_and_returnvalues" would be better?

Actually, the new option generates type hints to the documented parameters and the return value. So current proposal does not mention about the latter one. So "documented_params_and_returnvalue" describes the behavior more than now.

I added a new parameter to augment_descriptions_with_types() to pass the info if the return type should be annotated or not. This could also be solved by passing the config object. Would that be better?

LGTM.

The new option was not added to the documentation yet.

Yes, please. You also have to add testcases for the new option. Please refer tests/test_ext_autodoc_configs.py and tests/roots/test-ext-autodoc/.

[gschwaer]

I need to know more cases that are difficult to describe the return value. Do you have real examples? It would be helpful for me to imagine how this proposal is worth.

Hm, I would not say it is difficult to describe the return value. On the contrary, there are cases where the return value is perfectly described by its type. I don't have a real-world example that I can disclose, but here is a reasonable fictional example:

Assume we use autodoc_typehints_description_target = "documented" (reasons below) and we have a serialization method. The method has the docstring (let's not debate if this is the perfect docstring 🙃):

"""Serialize this object to be transmittable."""

The method has no parameters, so autodoc will add no annotations. Now there might be the question: To what is it serialized? str, bytes, or something completely different? So we can add :return: the serialized object, then the type is added by autodoc, like so:

"""Serialize this object to be transmittable.

:return: the serialized object
:rtype bytes:
"""

Now we have two extra lines in the documentation and one of them is redundant information. Our documentation gets bloated by that (imagine 20 more of this kind). The description of the return value is not really helpful, but we need it for autodoc to generate the return type annotation.

Why don't we just use autodoc_typehints_description_target = "all" and then omit the :return: part?

Assume we are writing a library and use sphinx to generate an API documentation for a 3rd party that'll use the lib. Internally we use some exposed methods in a special way, which we achieve by setting an optional flag parameter. We don't want this flag parameter to be documented, because the library users are not supposed to use this flag. Yes, we could use a level of redirection to hide the internal methods, but that bloats our code just to make sphinx work the way we need. Also it will break extensions like sphinx.ext.viewcode.

Now, assume we use the proposed feature (autodoc_typehints_description_target = "documented_params_and_returnvalue"):

In this case the return type is added without the need for the return value description. The resulting docstring is concise, contains all information needed to document how this method is to be used and no redundant information:

"""Serialize this object to be transmittable.

:rtype bytes:
"""

Actually, the new option generates type hints to the documented parameters and the return value. So current proposal does not mention about the latter one. So "documented_params_and_returnvalue" describes the behavior more than now.

I fully agree. I think your proposed option name can be misunderstood: (documented params) and returnvalue vs. documented (params and returnvalue).

• What about returnvalue_and_documented_params?

Yes, please. You also have to add testcases for the new option. Please refer tests/test_ext_autodoc_configs.py and tests/roots/test-ext-autodoc/.

Ok, I will do so, thanks for the pointers!

[gschwaer]

I added the new option to the documentation (target v4.3.) and wrote two tests with scenarios similar to the ones used for 'autodoc_typehints_description_target': 'documented'.

While testing the implementation I realized an oversight I did and corrected it: If the return type is None and no :return: description was given, it documented the return type. I think this makes not much sense, so I let autodoc ignore this exact case. If the return value has a description it will be annotated (both these cases are tested in test_autodoc_typehints_description_no_undoc_doc_rtype).

I ran tox with mypy and flake8 (both: no issues) and test-generated the documentation.

I think this should be it, please let me know if there is something I should change or add. 👍

[tk0miya]

Thank you for your explanation. It opened up my eyes :-) Now I perfectly understand your situation. +1 for adding the option.

The remaining task is naming. I don't still satisfy your (and my) proposal. Indeed, they surely describe their behavior correctly. But they are too descriptive and long. I think the new option will be used more than "documented_params". So it would be nice if we can find the better name. I'll try to find it for a few days. Please wait until then.

BTW, the master branch is used to develop the next major release 5.0. So it would be better to rebase this into the 4.x branch. Could you rebase this please?

[tk0miya]

Note: I think this will be merged after the 4.3.0 release. So I changed the milestone of this PR to 4.4.0 now.

[gschwaer]

Hi, I rebased the branch. Did you have an idea for the naming?
Since the others are: 'all' and 'documented', maybe a shorter option would be 'rtype_documented'. What do you think?

[tk0miya]

I and @shimizukawa discussed the name of this option. And we determined to call it documented_params. It does not mention to the annotation for "return value". But it's enough.

[tk0miya]

Merged. Thank you for your great work!