On Jun 8, 2:17 pm, kj <[EMAIL PROTECTED]> 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.
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. -- http://mail.python.org/mailman/listinfo/python-list
