epydoc隐藏了一些类函数？

Question

我的类中有一些方法，这些方法仅供该类的其他方法使用。我给他们的名字加上了'_‘前缀。我可以对epydoc隐藏这些函数吗？这是个好主意吗？

我应该使用'_‘还是双下划线？老实说，在一些地方读到它们之后，我没有得到不同之处。这种命名约定是否应该仅用于模块/类(实例)函数？或者也是变量？

Answer 1

如果你想隐藏所有的私有方法和私有变量，将选项'--no- private‘传递给epydoc。

请注意，对于epydoc，一个方法或变量在以下情况下是私有的：

and

• its名称以下划线'_‘开头，而不是以下划线'_’结尾。and

• you未将其名称包含在特殊的all字典中。

或者，您可以使用'undocumented‘标签来强制epydoc完全忽略某些方法或变量。

例如(这里我假设是一种ReStructured文本格式)：

class MyClass:
  """Some neat description

  :undocumented: x
  """

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

将导致文档仅包含私有(除非您使用了‘--no- _y’选项)和z。即使x不是私有的，也不会有任何关于x的内容。

私有方法是否应该在最终文档中可见，这是一个品味问题。对我来说，文档是由那些对内部实现不感兴趣或不应该感兴趣的人阅读的。私有方法最好是完全隐藏的。