[Doc-SIG] Attributes and also namespace pollution

[Tony J Ibbs (Tibs)]

Two "odds and ends" things left...

David Goodger wrote:
> > 258:`Attribute docstrings`_ item 1
> >
> >     Does this really mean to leave functions out? That is, can one
> >     really not do::
> >
> >         def fred():
> >             a = 1
> >             """``a`` is a silly name for a value."""
>
> 'a' is a local variable, and not of interest to the outside world.
> It's an implementation detail, best documented with a comment (or,
> better yet, with a self-documenting, descriptive name). In other
> words, 'a' is only of interest to someone reading the code itself,
> not to someone calling the function, so there's no need to document
> it externally.

Ah - hits forehead and says "d'oh". Yes, I should have thought of that.
On the other hand, that's a Good explanation - is it worth adding it as
a footnote for other fools like me? (hmm - probably not)

> > Other names
> >     OK, so the DPS is responsible (in some sense) for the
> >     __docformat__ name. Should it also be aware of some
> >     of the other (semi) standard names that people use
> >     - the following are ones I'm aware of:
...
> I don't like to see such namespace pollution. Once we open the door on
> these names (and admittedly it's already at least partially open), we
> can't close it. That's one reason why I added field lists to the spec,
> so they could be leveraged for bibliographic information.

Hmm. Personally, I like them ("namespace pollution" - only if one
doesn't like them!) - and they've historically provided a neat solution
to a problem given lack of docstrings.

Also, I don't think your field lists are powerful enough to cope with
these (authors, for instance, can get quite long and complex). But
that's a discussion I've still to start properly (hah - time).

> Should the DPS support the above? Maybe. I'd prefer that it didn't.
> That information is documentation, and doesn't need to take up more of
> the global namespace.

Hmm - there *is* an argument for having particularly important things
that one needs to know abot a module accessible using (for instance)
``dir``, without having to use special tools.

Does distutils/catalog stuff use any of these? I'm afraid I can't
remember.

> If you look at the pydoc output for modules
> which have these variables, it's very ugly.

Not an argument - at the moment, the pydoc output for *everything* is
ugly - that's because it's an early version of the tool, optimised for
*finding* information, not for presenting it well. Things will change.

> I'd want to avoid
> contributing to the further proliferation of these variables. If we
> support them, any of them, it just encourages the practice.
>
> I'd rather leave this up to a BDFL pronouncement, if Guido is willing.

I definitely think this is a matter on which to seek BDFL guidance - it
is clearly a matter of the style of the language-as-a-whole. Since I
assume he's not got the time to pay attention to Doc-SIG at the moment,
will you ask him? (I trust you to present both sides of the argument!).

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
"How fleeting are all human passions compared with the massive
continuity of ducks." - Dorothy L. Sayers, "Gaudy Night"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)