python中的docstring用法_在python模块docstring中放什么？

想想有人在交互式解释器的提示下做help(yourmodule)-他们想知道什么？（其他提取和显示信息的方法在信息量方面大致相当于help）。因此，如果您在x.py中有："""This module does blah blah."""

class Blah(object):

"""This class does blah blah."""

然后：>>> import x; help(x)

显示：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__ =

| dictionary for instance variables (if defined)

|

| __weakref__ =

| list of weak references to the object (if defined)

如您所见，这些类的详细信息（以及函数，尽管我在这里没有展示）已经包含在这些组件的docstring中；模块自己的docstring应该非常概括地描述它们（如果有的话），而应该集中在模块作为一个整体可以为您做什么的简明摘要上，理想情况下使用一些doctested示例（就像函数和类理想情况下应该在其docstring中包含doctested示例一样）。

我看不出诸如author name和copyright/license之类的元数据是如何帮助模块的用户的——它更愿意加入注释，因为它可以帮助人们考虑是否重用或修改模块。