[SciPy-dev] Documenting classes

[Robert Kern]

On Tue, Jun 17, 2008 at 14:59, Stéfan van der Walt <stefan at sun.ac.za> wrote:
> 2008/6/17 Robert Kern <robert.kern at gmail.com>:
>> On Tue, Jun 17, 2008 at 08:10, Stéfan van der Walt <stefan at sun.ac.za> 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
the source.

-- 
Robert Kern

"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