epydoc隐藏某些类函数？

Question

我在我的类里有一些方法，这些方法只打算被类里的其他方法使用。我在它们的名字前加了一个'_'。我可以把这些函数在epydoc里隐藏起来吗？这样做好不好？

我应该用'_'还是用双下划线呢？老实说，我在一些地方看了之后还是没搞明白它们的区别。这个命名规则应该只用在模块/类（实例）函数上吗？还是也可以用在变量上？

Answer 1

如果你想隐藏所有私有的方法和变量，可以在使用epydoc的时候加上'--no-private'这个选项。

需要注意的是，在epydoc中，什么算是私有的方法或变量呢？主要有以下几个条件：

• 它的名字以一个下划线'_'开头并且
• 它的名字不以下划线'_'结尾并且
• 你没有把它的名字放在一个特殊的all字典里。

另外，你也可以使用'undocumented'标签来强制epydoc完全忽略某些方法或变量。

举个例子（这里假设使用的是ReStructured Text格式）：

class MyClass:
  """Some neat description

  :undocumented: x
  """

  def _y(self): pass
  def x(self): pass
  def z(self): pass

这样做的话，文档中只会包含_y（除非你用了'--no-private'选项）和z。x则不会出现在文档里，即使它不是私有的。

至于私有的方法在最终文档中是否应该可见，这个问题其实是个人喜好的问题。对我来说，文档是给那些不应该关心内部实现的人看的。私有的方法最好是完全隐藏起来。