Pulp

Task #2347

Updated by amacdona@redhat.com over 7 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