[Doc-SIG] SGML Python docs

[Cees de Groot]

fdrake@cnri.reston.va.us said:
>  Good docstrings and good reference documentation are not necessarily
> related. 

That, of course, depends on how far you want to go with literate programming 
aspects in docstrings - more a voting issue than anything else. I vote for the 
inclusion of reference documentation in the sources, on a level comparable 
with Javadoc or POD (more the former than the latter, though). By adopting a 
"first-sentence" convention like Javadoc, docstrings can still be used for a 
compact on-line reference. The reason: I've never seen a project where 
separate source and documentation files where kept in synch.

-- 
Cees de Groot               http://pobox.com/~cg          <cg@pobox.com>
--- We're hiring Java developers => www.acriter.com