[Doc-SIG] Docstring: a newbie's two bits

[David Goodger]

Let me introduce myself. I am an experienced programmer with a plethora of
languages under my belt (C/C++, Pascal, the dreaded BASIC, Lisp/Scheme,
Perl, csh/ksh/bash scripting, AppleScript, and others in passing). I delved
into Python about a year ago, and loved it. I have 3 years intense
experience in an SGML analysis/design/processing environment. I have been
reading the Doc SIG digests for about a week, plus some back issues from the
archive. Please forgive me if I cover old ground.

I am about to release a set of (relatively small) open-source libraries &
tools. I have been using the docstring mechanism for internal documentation
all along, and was delighted to find there were tools available to extract &
mark up docstrings into something usable as documentation. Imagine my relief
when I learned that I didn't *have* to use TeX if I wanted to use standard
tools!

As a newbie, without any affiliation to one approach or another, I thought
I'd give you some opinions about the current docstring discussions. Please
take it as a vote from a typical (atypical?) member of the intended
audience. No offense to anyone is intended (nor, I hope, taken).

They take a little getting used to, but the rules of Structured Text (as at
http://www.python.org/sigs/doc-sig/stext.html) are easy to apply. I wouldn't
want to see much more tagging than this, however. I use docstrings as
working documentation, to be written in parallel with (ok, slightly *after*)
writing the code. And I refer to this documentation also, so it **must** be
readable (see? I'm already using the StructText conventions!). The docstring
documentation (as output by the tools) would only be a start for final
publication-quality documentation, however, so I'm not worried about lack of
fine-tweaking control.

HTML is great for quick & dirty user documentation or for on-screen display,
but its formatting-oriented tagging makes it next to useless for anything
more ambitious. I am pleased to hear that an effort is underway to create an
SGML/XML DTD, a la DocBook (PyBook?) or whatever.

Specifics:

- I would not use any kind of [tag content] or tag[content] or <tag/content/
explicit tagging. It's too confusing when reading the code itself. It's a
fine line that must not be crossed if this docstring proposal is going to be
used widely.

- I do like the output of Ka-Ping Yee's manpy very much (colouring aside
:-). When will it be available? This is what I call "usable" documentation.
Little more is needed at this level.

- Edward Welbourne's example (below) makes sense to me. Using quotes as
implicit "code" tagging would interfere with using them as explicit content,
and I don't see a better candidate than # on my keyboard. However, I am
uncomfortable with the "!" (exclamation point). Is there a reason why ":"
(colon) shouldn't be used? I think "mode : string" looks a lot more natural.

    Arguments:
        mode ! string -- the file access mode string ...  If #mode#'s
        first letter is #'r'#, #file# must exist.

-- 
David Goodger (pronounced as in "badger", but good)    dgoodger@bigfoot.com