Q re documentation Python style

[Bruno Desthuilliers]

kj a écrit :
(snip)

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

Python supports keyword (named) arguments, so you don't have to remembed 
the order, ie:


def func(arg1, arg2, arg3, arg4):
    # code here


func(arg2=42, arg4="toto", arg3="truc", arg1="foo")


Also, with good enough naming (perhaps one of the most difficult part of 
programming FWIW), you don't necessarily need an exhaustive 
documentation of each and every detail.


(snip)

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

Or to learn how to hook into the system. If you want to put the doc 
before or after the function's body,  it is not a big problem:


# doc after the function's body:

def func(args):
    # code here

func.__doc__ = """
doc here
...
"""



# doc before the function's body:

def document(doc):
   def _document(func):
     func.__doc__ = doc
     return func
   return _document


@document(""" doc here
and here and here
etc...
""")
def func():
   # code here


I wouldn't personnaly use any of the above styles, but as far as I'm 
concerned, I don't write exhaustive docstrings. Good naming (somehow one 
of the hardest part in programming IMHO) and simplicity (small simple 
functions doing one thing each) already provide some part of the 
documentation IMHO, and code always provides the most exhaustive 
documentation you'll ever find !-)