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?

Serum

Use single underscore by convention. Using it on other types of variable is accepted (as far as I know), although methods & functions are the most common uses. – Fortieth

ok, any ideas how to make them hidden to epydoc though? – Serum

Sorry, no. I haven't used epydoc. – Fortieth

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.

Capsize

or @undocumented: x in epytext syntax. – Gazelle