[SciPy-dev] Documenting classes
Tue Jun 17 15:59:38 CDT 2008
On Tue, Jun 17, 2008 at 14:59, Stéfan van der Walt <firstname.lastname@example.org> wrote:
> 2008/6/17 Robert Kern <email@example.com>:
>> On Tue, Jun 17, 2008 at 08:10, Stéfan van der Walt <firstname.lastname@example.org> wrote:
>>> On the other hand,
>>> methods can be inspected (i.e. TAB-completion in IPython, 'help' or
>>> 'dir' in the raw shell), so we don't need to list the methods, as
>>> suggested in the PEP:
>>> "The docstring for a class should summarize its behavior and list the
>>> public methods and instance variables."
>> That said, it can be difficult to pick out which methods are public
>> and important, and which aren't.
> Maybe it's a good idea to make this implicit in the naming: start the
> function name with an underscore if it is not part of the public API.
Even then, there is a difference between a public API and the
interesting subset. For example, memmap subclasses ndarray. The
interesting additional method is flush() which should be mentioned in
the docstring because a user would never discover it without reading
"I have come to believe that the whole world is an enigma, a harmless
enigma that is made terrible by our own mad attempt to interpret it as
though it had an underlying truth."
-- Umberto Eco
More information about the Scipy-dev