Speaking of visual assaulting format.... rewritten as a Task I hope I am not stepping on toes here, but if I was going to take the time to get format this in a way that makes my point, I figured I might as well go ahead and do it on an issue.
https://pulp.plan.io/issues/2347 On 10/18/2016 08:15 AM, Austin Macdonald wrote: > tldr; I'm strongly in favor of switching to Napoleon. I was not > previously opinionated on the matter, but after trying it out I see a > lot of benefits. > > Reasoning: *We drown ourselves with useless information.* > > :param repo_name: The name of the repo > :type repo_name: basestring > > This obviously has a very low information density. > > > In Napoleon this would be: > > Params: > repo (basestring): Name of a repository > > 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: > > _ > __Current_ > > 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 under the > attribute > "distributors" > > > :type distributors: > bool > > > > > > > > :return: a list of serialized repositories with importer and > distributor data optionally > added > > > :rtype: list of > dicts > > > > > """ > > > > > _Napoleon > > _ 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: > > > > > A list of serialized repositories with importer and distributor > data optionally > added > > > """
signature.asc
Description: OpenPGP digital signature
_______________________________________________ Pulp-dev mailing list Pulp-dev@redhat.com https://www.redhat.com/mailman/listinfo/pulp-dev
