[DOC-SIG] A few thoughts on the docstring standards

[Friedrich, Robin K]

>----------
>From: 	Ken McDonald[SMTP:kmcdona@watson.wustl.edu]
>Sent: 	Monday, December 08, 1997 1:17 PM
>To: 	doc-sig@python.org
>Subject: 	[DOC-SIG] A few thoughts on the docstring standards
>
>Was just using the basic format outlined on the SIG special interest
>page, and it's nice--concise, easy to remember, fast to type. This has
>likely been discussed before, but I didn't see it in the recent SIG
>mail traffic, so will just mention a quick couple of points here.
>
>1) Do **bold** and *italic* apply in example code? The format says
No. 
>example code is printed "verbatim", but hopefully this applies only to
>indenting--it'd be very nice to be able to italicize and bold things in
>code (**keywords**, *placeholders*, etc.) But then one has to worry about
>actual * usages in code, including in RE's where there might not be the
>option setting the asterisk up so it is interpreted as an asterisk.
Yes this is the rub as it complicates the scanning RE greatly. So we
just punted
saying that it wasn't all that important.
>
>2) There was a mention of restricting the usage of '--' to avoid
>confusion between " desc -- a descriptive list element", and other usages
>(such as a hyphen). For myself, simply saying that -- only has its special
>meaning if surrounded by whitespace would be fine.
OK that's what's done now but how does this help other uses of -- as
they are likely to be surrounded by whitespace anyway?
>
>3) Is this effort still going on? The mention of gendoc says the last
>update was Sept. 96. This isn't a criticism, I'm just wondering if the
>effort has headed in some other direction. (Don't want to use obsolete
>standards!)
The motivation for that documentation last year was the active work on
gendoc. Gendoc work may be resurrected soon and then we revisit these
standards more intensely*. However, I don't see any competing doc string
markup standards being seriously proposed, so you are safe in using it. 

* On this note I'd like to see if anyone really wants to see a project
for a comprehensive python source documentation toolkit? By "really
wants" I mean is willing to contribute design and coding to such an
effort. I'd hate to ask Daniel Larsson to redo his tools again without
serious help. I know recent comments seem to indicate that a full
remodeling is desired by some.

Robin F.

_______________
DOC-SIG  - SIG for the Python Documentation Project

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