[DOC-SIG] doc strings

[Friedrich, Robin K]

To follow up to Ed's doc string comments let me restate the latest
structured test proposal. I will not comment on an API for this meta-
information; that's a subject for another thread once we have agreed
to the contents of doc strings. This discussion follows from the
need for doc strings substantive enough to allow a reasonable user's
guide to be automatically generated with tools such as gendoc. 
That places it roughly in Guido's 4th category of doc string use.

For those who have not read the DOC SIG web page recently this posting
will try to encapsulate all current structured text capabilities as
working in gendoc 0.6 as well as some proposed enhancements.
[but please do read http://www.python.org/sigs/doc-sig/]


"""This is a one line description of the functionality.

A more detailed discussion of the object's function and purpose
may follow. Otherwise the author may choose to jump right into
the object's prototype information. I will identify optional key
text used for parsing in [bracketed] notation. As it stands now,
brackets have no special meaning. Subordinate paragraphs are
simply indented. Structured text currently has some implied rules
for determining what paragraphs are tagged as headers. (I for one
would like to see some more attention paid to that detail.) Any 
special characters like '<' for HTML need not be escaped in any
way as the renderer will be responsible for that.

	*Note* that "hyperlinks" are delimited by double quotes. In effect
	what this does is cause the string in the quotes to be saved off for
	further comparison to the URL lines at the end of the doc string. For
	an HTML rendering the quotes themselves would be removed and any
	quoted text which doesn't match exactly will be left alone. 
	
	Text on a single line surrounded by asterisks are tagged as
	'emphasis' (italic in HTML), while text wanting to be **loud** is
	surrounded by double asterisks and are tagged 'strong' (bold in
	"HTML" viewers). 
	
	Class objects should only document the class interface and leave the
	method doc to those individual doc strings. (This is not a hard rule
	as I've seen many coders insist on placing everything in the class
	doc.)

The following is new structure to support identification of function
prototype information.

[Required] Argument[s]:
	arg1 -- String containing a source file name.
	arg2 -- String containing a target file name.

Optional Argument[s]:
	arg3 -- (-1) Integer defaulted to -1 as shown by the parenthesis.
		Other text not having a double dash will be appended line's
		string; otherwise it would signify a new def list item. Ed
		marked optional arguments with brackets. Since any argument
		with a default value is optional this may not be necessary.
	arg4 -- ('') String. This is identified as new list item without
		having to have a blank line separating them. For long lists
		this is important. Note also that single quotes indicate
		literal (code) text and great care must be taken in the 
		parser to get this right. We might discuss alternative
		notation for literal strings. 

Keyword Argument[s]:
	opt1 -- (1) Defaults for python keywords are implemented in code so
		they cannot be extracted for the function declaration.
	opt2 -- (None) These lists can get mighty long.

Return Value:
	Tuple pair (perigee, apogee).

Example Usage:
	Any line ending in a colon containing the string 'example' will flag
	the following indented paragraphs as preformatted code until
	indentation returns to the next leftward level. This is not
	structured text protocol currently but is just an idea. This differs
	from the single quote usage which is just intended for short literal
	text not spanning lines.

* Bulleted lists can appear at any level of indentation and can be
	identified by either a '*', 'o', or a '-' as the first nonwhite
	character on the line. 
	* Indented bullet paragraphs are rendered accordingly.
	* Bulleted list items need not be separated by blank lines.
	* This is another item that's not easy to parse as a paragraph may
	start with *emphasized text*. 

.. "hyperlinks" http://www.python.org/sigs/doc-sig/
.. "HTML" http://www.w3c.org/
"""



_______________
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
_______________