Project

Profile

Help

Task #2347

Updated by amacdona@redhat.com about 4 years ago

Reasoning: Our docstring formatting could be easier to visually parse.

*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 Google docstring style 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 easier on less visually assaulting. On the eyes.

It would also be easier to scan if
topic of
visual assualt, `:param:` is
the first part of the line was a line, which is where
I would rather be scanning for
variable names. **Google docstring style
name instead of `:param:`. 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):
:type distributors: bool
"""
</code></pre>

In Google docstring style 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>

We can use Napolean[0] as a Sphinx plugin to enable support for Sphinx to consume and present Google style docstrings.

[0]: http://www.sphinx-doc.org/en/stable/ext/napoleon.html

Back