什么放在python模块docstring？ [英] What to put in a python module docstring?

问题描述

好的，所以我已经阅读了 PEP 8 和 PEP 257 ，我已经为函数和类写了很多文档，但是有一点不确定在一个模块docstring应该去什么。我认为，至少应该记录模块导出的功能和类，但是我也看到了列出作者姓名，版权信息等的几个模块。有没有人有一个例子，说明一个好的python docstring应该如何结构化？

解决方案

想想有人在做$ help（yourmodule）交互式口译员的提示 - 他们想要知道什么？ （提取和显示信息的其他方法大致相当于信息量的帮助）。所以如果你有 x.py ：

  $
 
 class Blah（object）：
这个类别是blah blah。
  / pre> 
 
 
然后：
 >>>进口x帮助（x）
  
显示：
 帮助模块x：
 
 NAME 
x  - 此模块使用blah blah。 
 
 FILE 
 /tmp/x.py 
 
 CLASSES 
 __builtin __。对象
 Blah 
 
 class Blah （__builtin __。object）
 |这个班级的确是blah blah。 
 | 
 |数据和其他属性定义在这里：
 | 
 | __dict__ =< dictproxy对象> 
 |字典为实例变量（如果已定义）
 | 
 | __weakref__ =<属性'__weakref__''Blah'对象> 
 |列表对对象的弱引用（如果已定义）
  
如您所见，类的详细信息（和函数，虽然我没有在这里显示）已经从这些组件的docstrings中包含;模块自己的docstring应该非常简要地描述它们（如果有的话），而是集中精力总结一下模块作为一个整体可以为你做什么，理想情况下是用一些doctested的例子（就像函数和类理想地应该有doctested的例子我不明白作者姓名和版权/许可等元数据如何帮助模块的用户 - 它可以放在评论中，因为它可以帮助有人考虑是否重复使用或修改模块。
 
Ok, so I've read both PEP 8 and PEP 257, and I've written lots of docstrings for functions and classes, but I'm a little unsure about what should go in a module docstring.  I figured, at a minimum, it should document the functions and classes that the module exports, but I've also seen a few modules that list author names, copyright information, etc.  Does anyone have an example of how a good python docstring should be structured?
解决方案
Think about somebody doing help(yourmodule) at the interactive interpreter's prompt -- what do they want to know?  (Other methods of extracting and displaying the information are roughly equivalent to help in terms of amount of information).  So if you have in x.py:
"""This module does blah blah."""

class Blah(object):
  """This class does blah blah."""
then:
>>> import x; help(x)
shows:
Help on module x:

NAME
    x - This module does blah blah.

FILE
    /tmp/x.py

CLASSES
    __builtin__.object
        Blah

    class Blah(__builtin__.object)
     |  This class does blah blah.
     |  
     |  Data and other attributes defined here:
     |  
     |  __dict__ = <dictproxy object>
     |      dictionary for instance variables (if defined)
     |  
     |  __weakref__ = <attribute '__weakref__' of 'Blah' objects>
     |      list of weak references to the object (if defined)
As you see, the detailed information on the classes (and functions too, though I'm not showing one here) is already included from those components' docstrings; the module's own docstring should describe them very summarily (if at all) and rather concentrate on a concise summary of what the module as a whole can do for you, ideally with some doctested examples (just like functions and classes ideally should have doctested examples in theit docstrings).

I don't see how metadata such as author name and copyright / license helps the module's user -- it can rather go in comments, since it could help somebody considering whether or not to reuse or modify the module.

                        
这篇关于什么放在python模块docstring？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！