Project

Profile

Help

Task #2347

Updated by amacdona@redhat.com over 4 years ago

Reasoning: *We drown ourselves with useless information.*
<pre>
:param repo_name: The name of the repo
:type repo_name: basestring
</pre>

This obviously has a very low information density.

In Napoleon this would be:

<pre><code class="python">


Params:
repo (basestring): Name of a repository
</code></pre>

Format can't fix awkward, and this is still not a super helpful comment,
but at least it takes up less space but contains the same information.
The lists will be shorter and less visually assaulting. On the topic of
visual assualt, `:param:` is the first part of the line, which is where
I would rather be scanning for variable names. **Napoleon presents
information in the order I look for it.**

Take a look at a comparison of larger docstrings from the wild:

<pre><code class="python">
def _process_repos(repo_objs, details, importers, distributors):
"""
Serialize repository objects and add related importers and distributors if requested.

Apply standard processing to a collection of repositories being returned to a client. Adds
the object link and optionally adds related importers and distributors.

:param repo_objs: collection of repository objects
:type repo_objs: list or tuple of pulp.server.db.model.Repository objects
:param details: if True, include importers and distributors, overrides other values
:type details: bool
:param importers: if True, adds related importers under the attribute "importers"
:type importers: bool
:param distributors: if True, adds related distributors udef _process_repos(repo_objs, details, importers, distributors):
"""
Serialize repository objects and add related importers and distributors if requested.

Apply standard processing to a collection of repositories being returned to a client. Adds
the object link and optionally adds related importers and distributors.

Args:
repo_objs (list or tuple of Repository): collection of repository objects
details (bool): if True, include importers and distributors, overrides other values
importers (bool): if True, adds related importers under the attribute"importers".
distributors (bool): if True, adds related distributors under the attribute "distributors"

Returns:
List of serialized repositories with importer and distributor data optionally added
""" nder the attribute "distributors"
:type distributors: bool

:return: a list of serialized repositories with importer and distributor data optionally added
:rtype: list of dicts
""

</code></pre>



In Napoleon this would be:

<pre><code class="python">
def _process_repos(repo_objs, details, importers, distributors):
"""
Serialize repository objects and add related importers and distributors if requested.

Apply standard processing to a collection of repositories being returned to a client. Adds
the object link and optionally adds related importers and distributors.

Args:
repo_objs (list or tuple of Repository): collection of repository objects
details (bool): if True, include importers and distributors, overrides other values
importers (bool): if True, adds related importers under the attribute"importers".
distributors (bool): if True, adds related distributors under the attribute "distributors"

Returns:
List of serialized repositories with importer and distributor data optionally added
"""
</code></pre>

Back