Q re documentation Python style

[kj]

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

 

[Diez B. Roggisch]

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?

Docstrings are it. Yet there are several ways how their content is
interpreted. Google for example epydoc. You can embed links that way.

I don't know perl, and even less it's documentation system. Yet I
wonder: *where* do you put your function documentation, if not at the
function? And if it is some sort of link (I guess it must be, or do you
declare function docs totally unrelated to the functions themselves?), I
have to say - I'd rather open the sourcefile and see what a function is
about than having to manually follow links.

Diez

 

[Carl Banks]

I'm a Perlhead trying to learn the Way of Python.

Welcome to the light, my son.

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?

You can define a decorator to inject the docstring; at least the
docstring will not come between the function line and the body.
Define the decorator like this:


def doc(docstring):
def inject_doc(function):
function.func_doc = docstring
return function
return inject_doc


And then you could do this:

@doc("This is the docstring.")
def some_function():
do_whatever()


I think most tools that use docstrings actually execute the module,
which means by the time the tool sees it the docstring will have been
assigned, though I'm not sure they all do.


Carl Banks

 

[John Machin]

[snip]

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

Like myfunc({'strarg': 'foo', 'intarg': 42}) ??
So the start of this function would look something like this:

def myfunc(dictarg):
strarg = dictarg['strarg']
intarg = dictarg['intarg']
# the real work starts now

Why not use keyword args?
.... print 'a1=%r a2=%r' % (a1, a2)
....
Have you read this section in the Python tutorial: "4.7 More on
Defining Functions" (http://docs.python.org/tut/
node6.html#SECTION006700000000000000000)

HTH,
John

 

[Paddy]

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.

Hi Kynn,
Strings on their own are also valid statements so if in Perl you might
documentbefore the sub statement or even after the function definition
then you could put extra information in a tripple quoted string
statement before your function and put the bare essentials in the
function itself. This would leave the def nearer the body of the
function, but I don't know of anyone else that does this.

- Paddy.

 

[bukzor]

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

you can assign a documentation string to the function's .__doc__
attribute. This allows you to place your documentation lower in the
script, or higher if you use an extra variable.

 

[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 !-)

 

[bearophileHUGS]

kj:

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.

You may put the main function(s) documentation in the docstring of the
module, and a much shorter version in the docstring of the function.

Bye,
bearophile

 

[kj]

Wow. That was a great bunch of advice.

Thank you all very much!

Kynn

 

[Ethan Furman]

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. [snip]
Kynn

You might also look into using an editor that supports custom folding.
Define docstrings as folds, then you only need open them when you want
to read/edit them; the rest of the time, only one line is visible
between the function header and the function. I like Vim.