Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.python > #32618

Re: Organisation of python classes and their methods

Show key headers only | View raw

On 11/2/12 10:21 AM, Peter Otten wrote:
> Martin Hewitson wrote:
>
>> On 2, Nov, 2012, at 09:40 AM, Mark Lawrence <breamoreboy@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/

In the science/math community, we tend to build the Sphinx API reference from 
the thorough, authoritative docstrings. We like having complete docstrings 
because we are frequently at the interactive prompt. We tend to have broad APIs, 
so having a single source of documentation and not repeating ourselves is important.

   http://docs.scipy.org/doc/numpy/reference/index.html
   http://docs.scipy.org/doc/scipy/reference/index.html
   http://www.sagemath.org/doc/reference/
   http://docs.sympy.org/0.7.2/modules/index.html
   http://scikit-learn.org/stable/modules/classes.html

-- 
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

Back to comp.lang.python | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread

Thread

Organisation of python classes and their methods Martin Hewitson <martinhewitson@mac.com> - 2012-11-02 07:16 +0100
  Re: Organisation of python classes and their methods Paul Rubin <no.email@nospam.invalid> - 2012-11-02 00:38 -0700
    Re: Organisation of python classes and their methods Martin Hewitson <martinhewitson@mac.com> - 2012-11-02 09:08 +0100
      Re: Organisation of python classes and their methods Ulrich Eckhardt <ulrich.eckhardt@dominolaser.com> - 2012-11-02 11:18 +0100
        Re: Organisation of python classes and their methods Martin Hewitson <martinhewitson@me.com> - 2012-11-02 15:49 +0100
        Re: Organisation of python classes and their methods Mark Lawrence <breamoreboy@yahoo.co.uk> - 2012-11-02 17:02 +0000
      Re: Organisation of python classes and their methods Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2012-11-03 01:38 +0000
    Re: Organisation of python classes and their methods Mark Lawrence <breamoreboy@yahoo.co.uk> - 2012-11-02 08:40 +0000
      Re: Organisation of python classes and their methods Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2012-11-02 10:20 +0000
    Re: Organisation of python classes and their methods Chris Angelico <rosuav@gmail.com> - 2012-11-02 20:15 +1100
    Re: Organisation of python classes and their methods Martin Hewitson <martinhewitson@mac.com> - 2012-11-02 09:45 +0100
    Re: Organisation of python classes and their methods Peter Otten <__peter__@web.de> - 2012-11-02 11:21 +0100
    Re: Organisation of python classes and their methods Mark Lawrence <breamoreboy@yahoo.co.uk> - 2012-11-02 10:48 +0000
    Re: Organisation of python classes and their methods Robert Kern <robert.kern@gmail.com> - 2012-11-02 10:55 +0000
    Re: Organisation of python classes and their methods Robert Kern <robert.kern@gmail.com> - 2012-11-02 11:07 +0000
  Re: Organisation of python classes and their methods Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2012-11-03 01:06 +0000
    Re: Organisation of python classes and their methods Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2012-11-03 01:08 +0000

csiph-web