Q re documentation Python style

[Timothy Grant]

On Sun, Jun 8, 2008 at 2:17 PM, kj <socyl at 987jk.com.invalid> wrote:

>
>
> I'm a Perlhead trying to learn the Way of Python.  I like Python
> overall, but every once in a while I find myself trying to figure
> out why Python does some things the way it does.  At the moment
> I'm scratching my head over Python's docstrings.  As far as I
> understand this is the standard way to document Python code.  I
> think that's fine for simple functions, but I have some functions
> that require a very long docstring to document, and somehow I find
> it a bit disconcerting to stick a few screenfuls of text between
> the top line of a function definition and its body.  I guess I'm
> still a lot more comfortable with Perl's POD, which allows more
> flexibility on the placement of the documentation relative to the
> source code.
>
> I expect that the reply to this quibble about very long docstrings
> will be something like: if your function requires several screenfuls
> of text to document, then it is too complex or it is doing too
> much; refactor it into a collection of simpler functions that will
> have shorter docstrings.
>
> Fair enough.  In general I agree with this sentiment, except that
> I think that sometimes even simple functions require a lot of
> documentation.  For example, I want to document a function that
> takes a dictionary as argument, and this dictionary is expected to
> have 5 keys.  (When the number of mandatory arguments gets above
> 4, I find that it's too difficult to remember their order, so I
> resort to using a dictionary as the single argument.)  The semantics
> for each of these keys needs to be described.  Plus, of course, I
> need to describe what the function returns.  That's a few screenfuls
> right there...
>
> I guess this is a rambling way to ask: are docstrings *it* as far
> Python documentation goes?  Or is there a second, more flexible
> system?
>
> Then again, I suppose that Python's relative formal rigidity is
> considered by many to be a strength.  Which means that, to be
> comfortable with Python, one has to learn to like this (relatively)
> rigid structure...
>
> But I thought I'd ask.  :)
>
> Kynn
>
> --
> NOTE: In my address everything before the first period is backwards;
> and the last period, and everything after it, should be discarded.
> --
> http://mail.python.org/mailman/listinfo/python-list
>

If you use named parameters in your functions and methods, order is not so
important...

>>> def foo(a=None, b=None, c=None):
...    print a,b,c
...
>>> b(c=1, a=2, b=3)
2 3 1


-- 
Stand Fast,
tjg.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-list/attachments/20080608/bb641924/attachment-0001.html>