[Dev] epydoc docstring formatting guide

[Mike Taylor]

In my travels thru the source code recently tracking down epydoc issues 
to fix the auto-generated documentation, I have found that we are all 
over the map when it comes to formatting doc-strings for use with 
epydoc.

Because the doc-strings are used to directly generate developer 
documentation *and* they are the first place other developers will go 
for information, I feel it's important to make sure that the 
doc-strings are all consistent and structured in a manner that will not 
break epydoc.

I have created a wiki page that shows a sample doc-string that touches 
on all of the major issues and shows the basic epydoc features:

http://wiki.osafoundation.org/bin/view/Projects/ChandlerEpydocStyleGuide

This is what I'll be using as a template when I fix doc-strings that 
are already in the source and what I suggest everyone should follow 
when working with code that is being commited from this point on.

thanks,

---
Bear

Build and Release Engineer
Open Source Applications Foundation (OSAF)
bear at osafoundation.org
http://www.osafoundation.org

bear at code-bear.com
http://code-bear.com

PGP Fingerprint = 9996 719F 973D B11B E111  D770 9331 E822 40B3 CD29

-------------- next part --------------
A non-text attachment was scrubbed...
Name: PGP.sig
Type: application/pgp-signature
Size: 186 bytes
Desc: This is a digitally signed message part
Url : http://lists.osafoundation.org/pipermail/dev/attachments/20050926/1dd494f9/PGP.pgp