Эпидок скрыть некоторые функции класса? - PullRequest
Новая
       14

Эпидок скрыть некоторые функции класса?

3 голосов
/ 04 октября 2011

У меня есть некоторые методы в моем классе, которые предназначены только для использования другими методами класса.Я поставил перед их именами '_'.Могу ли я скрыть эти функции от epydoc?Это хорошая идея?

Должен ли я использовать '_' или двойное подчеркивание?Честно говоря, я не получил разницы после чтения о них в некоторых местах.Следует ли использовать это соглашение об именах только для функций модуля / класса (экземпляра)?Или также переменные?

1 Ответ

4 голосов
/ 24 октября 2011

Если вы хотите скрыть все приватные методы и приватные переменные, передайте опцию '--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 ничего не будет, даже если он не является личным.

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

...