文档字符串中的重复内容

Question

如何处理文档字符串中的重复内容呢？我有很多函数都需要用到一些“标准”的参数，这些参数在文档字符串中需要解释清楚。不过，如果能把文档字符串中相关的部分只写一次，那就方便多了，这样维护和更新起来也简单。我之前试过这样做：

arg_a = "a: a very common argument"

def test(a):
    '''
    Arguments:
    %s
    ''' % arg_a
    pass

但是这样不行，因为当我输入 help(test) 时，看不到文档字符串。有没有好的方法可以解决这个问题呢？

Answer 1

据我所知，似乎没有明显的方法可以做到这一点（至少不包括像Ignacio建议的那样明确地重新赋值__doc__）。

不过，我觉得这样做会非常糟糕。想想看：

如果我在你的代码中浏览，正在阅读你文件第300行的文档字符串，你真的希望我去搜索这个参数吗？

Answer 2

__doc__ 是大多数用户自定义类型可以赋值的：

arg_a = "a: a very common argument"

def test(a):
    pass

test.__doc__ = '''
    Arguments:
    %s
    ''' % arg_a

Answer 3

正如其他回答所说，你需要修改函数对象的 __doc__ 属性。一个很好的方法是使用装饰器，这样可以对文档字符串进行格式化处理：

def fixdocstring(func):
    func.__doc__ = func.__doc__.replace('<arg_a>', 'a: a very common argument')
    #(This is just an example, other string formatting methods can be used as well.)
    return func

@fixdocstring
def test(a):
    '''
    Arguments:
    <arg_a>
    ''''
    pass