python - epydoc 隐藏一些类函数？

Question

我的班级中有一些方法仅供班级的其他方法使用。我在他们的名字前加上'_'。我可以从 epydoc 中隐藏这些功能吗？这是个好主意吗？

我应该使用'_'还是双下划线？老实说，在某些地方阅读了它们之后，我并没有得到区别。此命名约定是否应该仅用于模块/类（实例）函数？还是变量？

Answer 1

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

请注意 - 对于 epydoc - 方法或变量是私有的，如果：

• 它的名称以下划线“_”开头，并且
• 它的名称不以下划线“_”结尾，并且
• 您没有在特殊的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 不是私有的，也不会有任何关于 x 的内容。

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