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. Там не будет ничего о х, даже если это не личное.

Должны ли частные методы быть видимыми вообще или нет в итоговой документации - дело вкуса. Для меня документация читается людьми, которые не заинтересованы или не должны интересоваться внутренней реализацией. Частные методы лучше всего спрятать полностью.