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

[Ken McDonald]

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
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.

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.

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!)

Thanks,
Ken

========================================
Kenneth McDonald
Genome Sequencing Center
Washington University School of Medicine

Phone: 314-286-1831
========================================


_______________
DOC-SIG  - SIG for the Python Documentation Project

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