Organisation of python classes and their methods

[Peter Otten]

Martin Hewitson wrote:

> On 2, Nov, 2012, at 09:40 AM, Mark Lawrence <breamoreboy at yahoo.co.uk>
> wrote:

>> 20 lines of documentation per method?  As far as I'm concerned that's not
>> a smell, that's a stink.
> 
> Wow, I don't think I've ever been criticised before for writing too much
> documentation :)
> 
> I guess we have different end users. This is not a set of classes for
> other developers to use: it's a set of classes which creates a data
> analysis environment for scientists to use. They are not programmers, and
> expect the algorithms to be documented in detail.

While I would never discourage thorough documentation you may be better off 
with smaller docstrings and the details in an external document. Python 
projects typically use rst-files processed by sphinx.

http://pypi.python.org/pypi/Sphinx/