Question

我有一个类有几个类似的方法，每个方法都有很长的文档字符串，但是在几个短语/单词方面有所不同。我想构建一个docstring模板，然后对其应用字符串格式。下面是一个笨拙的实现，其中__doc__是在类方法之后定义的。

capture_doc = """
%(direc)s normal.

a %(sym)s b."""

class Cls():    
    def a(self):
        pass
    def b(self):
        pass
    a.__doc__ = capture_doc % {'direc' : 'below', 'sym' : '<'}     
    b.__doc__ = capture_doc % {'direc' : 'above', 'sym' : '>'}

c = Cls()    
print(c.a.__doc__)

below normal.

a < b.

问题：是否有Python文档或PEP规定的方法来执行此操作？我想保持基本的东西，我已经看到使用@Appender decorator，但认为我的需求有点花哨。

Answer 1

你不应该这样做。您似乎认为您的docstring只应该为那些使用您的代码并且需要 help 的人提供服务。

Docstrings应该为那些读取代码提供相关对象的某种形式的文档，因此这使得你的文档字符串值得一半。我怀疑是否有人愿意经历麻烦，不得不格式化这些字符串（在他们的头脑中或使用解释器）来弄清楚你的代码是做什么或它是如何工作的。

来自PEP 257：

什么是文档字符串？

docstring是一个字符串文字，它作为第一个语句出现   在模块，函数，类或方法定义中。这样的 docstring   成为该对象的 __doc__特殊属性。

[强调我的]

通过您的实施，可以迂腐地争辩说您没有文档字符串，尽管__doc__属性。

在类方法docstrings中使用字符串格式

1 个答案: