epydoc hide some class functions?

Question

I have some methods in my class which are only meant to be used by other methods of the class. I've prefixed their names with '_'. Can I hide those functions from epydoc? Is it a good idea?

Should I use '_' or double underscore? To be honest I didn't get the difference after reading about them in some places. Should this naming convention be used only on module/class (instance) functions? Or also variables?

Answer 1

If you want to hide all private methods and private variables, pass option '--no-private' to epydoc.

Note that - for epydoc - a method or variable is private if:

• its name starts with an underscore '_' and
• its name does not end with an underscore '_' and
• you did not include its name in the special all dictionary.

Alternatively you can use the 'undocumented' tag to force epydoc to completely ignore certain methods or variables.

For instance (and here I assume a ReStructured Text kind of formatting):

class MyClass:
  """Some neat description

  :undocumented: x
  """

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

will result in the documentation to contain only _y (unless you used the '--no-private' option) and z. There will be nothing about x even if it is not private.

Whether private methods should be visible at all or not in the final documentation is a matter of taste. To me, documentation is read by people who don't or should not have any interest in the internal implementation. Private methods are best hidden completely.