[Tutor] doc strings and structured text

[Daniel Yoo]

On Tue, 12 Jun 2001, W. Jarrett Campbell wrote:

> In my new python adventure I've seen lots of reference to 'doc
> strings' and 'structured text'.  I've even figured out how to generate
> some basic inline documentation using the ActiveState implementation
> of pydoc.  However, I haven't been able to find a really good,
> tutorial level reference explaining doc strings and structured text.

Hello!

There's a good explanation on document strings "docstrings" here:

    http://www.onlamp.com/pub/a/python/2001/05/17/docstrings.html

which should provide a high-level tutorial on what docstrings are about.  

Docstrings are small strings that we attach to functions: at the very
beginning of a function definition, Python lets us stick in a string.  
For example:

###
def invertDict(dict):
    """inverts a dictionary so that the keys become the values, and
       vice versa ."""
    newdict = {}
    for key, value in dict.items(): newdict[value] = key
    return newdict
###

That multi-line string above is the docstring.  What's neat is that we can
look at this docstring later on if we want a small reminder of how things
work:

###
>>> print invertDict.__doc__
inverts a dictionary so that the keys become the values, and          
       vice versa .
>>> invertDict({1:'one', 2:'two', 3:'three'})
{'one': 1, 'two': 2, 'three': 3}
###

Almost every function in Python has a docstring, which makes our life much
easier.  Docstrings can also be attached to classes.  There's even a
suggestion to allow docstrings to attach to pretty much everything, but I
don't think that feature is implemented yet.

How does this relate to the other topic of "structured text"?  Structured
text is an approach to let people use indentation in their docstrings as a
way of structuring things.  Think HTML, and you'll have the idea of
StructuredText.  The big difference is that StructuredText doesn't use
tags at all.

The ZopeBook (which is coming out by New Riders soon, yah!), is written in
StructuredText, so you can take a look at an extended example of it here:

http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/~checkout~/zope-book/Book/README.txt?rev=1.2&content-type=text/plain

(sorry about the long link)

So the basic idea is to make it easy to write really elaborate docstrings
without having to learn an HTML-like language.


Hope this helps!