[Doc-SIG] Doc-String Syntax
Moshe Zadka <email@example.com>
Thu, 3 Feb 2000 02:29:25 +0200 (IST)
Yet another one in my series of fuzzy outlines before the real spec, here
is my suggestion for doc-string syntax.
There are two kinds of tags: "short" tags and "long" tags.
Short tags have the syntax exemplified by [emph this is emphasized] (the
first word is the tag, and it continues to a nested bracket.
Rational: this way tags can be written without touching the "shift" keys
on most keyboards.
Long tags have the syntax exemplified by
arg name=s type=string::
string to be parsed
The special long tag 'example' will not be intepreted by the program,
['this', 'is', 'a', 'list']
will work with no problems
the special long tag 'code' will work the same way, but will be translated
to inline code:
you can also write
(lambda x: [x])(5)
to return a list containing 5.
Paragraphs are seperated by new lines.
Another long tag, which is only valid in a classe's docstring, are
'instance-attrs' (unlike 'data', which would be class attributes).
All of the current semantic markup would be moved to short tags:
[module urllib], [class URLOpener] and [function urlopen] are all
Spec, as promised, on Friday.
Moshe Zadka <firstname.lastname@example.org>.
INTERNET: Learn what you know.
Share what you don't.