[Doc-SIG] Re: doc PEPs

[David Goodger]

[cc'ing to Doc-SIG]

Hi Greg,

on 2001-06-03 12:09, Greg Wilson (Greg.Wilson@baltimore.com) wrote:
> Thanks for writing up your PEPs --- as someone
> who teaches Python on a semi-regular basis, I've long wanted
> more structure in the internal docs.

I think it's a very common wish.

> One question, though:
> there have been proposals to replace or augment doc strings
> with doc dicts, so that if the first item in a module or
> function is an unassigned dict, its key/value pairs would
> become the item's docs.  I didn't see this possibility in
> your PEPs --- have you considered it?

No, I hadn't considered it. Off the top of my head I see some problems with
"docdicts" (it's always easier to think up negatives than positives ;):

1. Dictionaries have no order. How would we know which entry goes where?

2. Runtime pollution. Do we need to access these extra docs at runtime?
   If not, why use up the space?

3. Ambiguity. Would you overload __doc__, or add a new __docdict__?

The runtime pollution issue is circumvented by "additional docstrings"
because they're discarded by the bytecode compiler. That may also be the
case with literal dictionary expressions; I haven't checked.

> Do you think it would be worth including discussion of it?

Sure, if you or anyone else has enough interest to write up a proposal
(addressing at least those issues I brought up above), I'd be happy to
include it. I can't say that I see the usefulness of it though. Perhaps an
example? If you have any links to earlier discussions, I'd like to take a
look.

Thanks for the feedback.

-- 
David Goodger    dgoodger@bigfoot.com    Open-source projects:
 - Python Docstring Processing System: http://docstring.sf.net
 - reStructuredText: http://structuredtext.sf.net
 - The Go Tools Project: http://gotools.sf.net