python - epydoc 隐藏了一些类函数？

Question

我的类中有一些方法只能由类中的其他方法使用。我在他们的名字前加上了“_”。我可以从 epydoc 中隐藏这些功能吗？这是个好主意吗？

我应该使用“_”还是双下划线？老实说，在某些地方阅读了它们之后，我并没有发现其中的区别。这个命名约定应该只用于模块/类(实例)函数吗？还是变量？

Answer 1

如果您想隐藏所有私有(private)方法和私有(private)变量，请将选项“--no-private”传递给 epydoc。

请注意 - 对于 epydoc - 如果满足以下条件，则方法或变量是私有(private)的:

• 其名称以下划线“_”开头和
• 它的名字不以下划线'_'结尾和
• 您没有将其名称包含在特殊的all 词典中。

或者，您可以使用“未记录”标签强制 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 不是私有(private)的，也不会有任何关于 x 的信息。

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