[Doc-SIG] two simple, but important questions

[Tavis Rudd]

Edward suggesed:
> scope.  So maybe we can divide it in two:
>   PEP A: a standard markup/string format for "formatted documentation
>          strings"
>   PEP B: a proposal on how "formatted documentation strings" should
>          be accessed, where they should be stored, etc.
Or maybe it would be best to just have one PEP, with Edward's B (my 
questions, etc.) kept very small (a paragraph should do it once there's 
agreement here).

After reading Tibb's and Edward's responses to my questions, I'm starting to 
lean towards option a (keeping everything in the docstring) for the simple 
reason that it's the path of least resistance (/debate).  However, option b 
(having the option of a second string literal that follows the docstring and 
is discarded by python at complile-time) does provide the following things 
that option a can't:
- the ability to gracefully document module and class data attributes 
(constants etc.) as Marc-Andre Lemburg proposed in PEP 224
- a means for the verbose to document to their heart's content without 
worrying about increasing memory usage and load-time (but is this ever really 
going to be significant??)
- a means to include the Library reference documentation in the same file, as 
Ping proposed 

Of course, if the tools were to give module creators the option of putting 
extended documentation in like this, it doesn't mean that everyone must do it 
this way.  If you, as a coder, don't like the idea of discardible string 
literals after the __doc__s, stick with the standard docstring. 

> In general, if you want the docs on a module, then you should trust it
> enough to import it anyway.  Presumably if you're trying to get its
> docs, it's because you want to *use* it...
My concern here was related to indexes/searches of all available 
modules on a system, and to cases where module creators haven't followed the 
if __name__ == '__main__' convention.  But after thinking a bit harder, I 
realize that this is really an implementation issue for the tools and that 
security risks can be kept minimal with either route anyway.  Maybe the PEP 
should explicitly mention this as being an implementation detail for the tool 
makers.

Cheers,
Tavis
p.s. Edward there's no Tr in my name, just Ta