[Doc-SIG] Attributes and also namespace pollution
Tony J Ibbs (Tibs)
tony@lsl.co.uk
Wed, 8 Aug 2001 10:08:39 +0100
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.)