[Doc-SIG] suggestions for a PEP
Tony J Ibbs (Tibs)
tony@lsl.co.uk
Fri, 16 Mar 2001 10:25:34 -0000
Hmm - Eddy's back in the fray (with the combination of Eddy and Edward -
heh, that actually works!) I think things are sure to be, erm,
interesting (challenging? certainly needful of careful thought before
ponficating - oh, well, it wasn't going to last - I'm *good* at
pontificating (no, I didn't mean that it's *well received*, I just meant
it's a mode I'm good at dropping into)).
Eddy (i.e., Edward Welbourne, fuller-named) said:
> yes, but doc-sig regulars have had so much practice at these
> argument (at most a year between iterations) you should be
> able to moderate the general list-population's discussion
> quite tightly ;^>
The problem is (licks finger and holds it up in the air - yes)
threefold:
1. Rehashing arguments you've had before several times is boring
2. BUT it IS still worth rehashing them, because sometimes one
changes one's mind (been there, done that)
3. unfortunately, it *does* take up a lot of time and typing
(and it isn't *really* fair to just say "we discussed that,
it's in the archive, tough" - although it's *tempting*!)
> On assigning docstrings:
> erm ...
>
> Python 1.5.2 (#5, Oct 4 1999, 13:36:16) [GCC 2.7.2.3] on linux2
> Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam
> >>> def hello(there): return there
> ...
> >>> hello.__doc__ = 'hello there'
> >>> hello.__doc__
> 'hello there'
>
> if it fails in 2.*, eek !
Hmm - trying (also in 1.5.2):
>>> class fred:
... def f1():
... """f1"""
...
>>> class jim:
... def j1():
... pass
... j1.__doc__ = fred.f1.__doc__
...
>>> jim.j1.__doc__
'f1'
Well, that's what I was thinking of - I can't imagine it's broken in 2.n
On the other hand, I can't help feeling that what I'd *really* do is
give #j1()# a docstring that just said::
"""This should behave identically to #fred.f1()#, which see."""
('cos that's *documentation* of what I mean). Still, whilst I might not
want to do it, Python is clearly meant to *allow* what Edward (L) wants
to do, so I shan't try to make it harder...
acquisition - hmm
> [Then again, I tend to put big
> parenthetical texts into square brackets rather than curved ones, but
> I'm guessing Tony's proposed usage as link-generators will only apply
> when there's only one word in the interval ?]
Not even one word - it will have to be an identifier (in the XML sense,
a <I forget the details> name - which is, I think, much the same as a
Python identifier).
(btw, Edward (L), I *think* it should be possible to make dodgy and
erroneous constructions emerge in the DOM tree marked up as such - that
is, for instance, "badpara" instead of "para" or "dlist" or whatever -
or maybe as an attribute - so that a renderer can highlight things
appropriately - I've some notes I want to compare with the source code
this weekend to see how feasible it is.)
I would certainly expect to do #[1,2,3]# in STpy docstrings, rather than
[1,2,3] (in STClassic, I would have expected to do '[1,2,3]', so that's
not much different).
Eddy then got into "agreement with me" mode, which is always a bit
worrying - one waits for the other boot to drop (or whatever the saying
is)
> > Possibly in a different file.. I find Tibb's arguments
> > pretty convincing..
> Tibs is like that. Get used to it and *use* him ;^>
Hmm. I thought I was the one who always got off on the wrong foot, had a
long argument defending an indefensible position, and then finally
collapsed with "oh, I see, yes you're clearly right". Which is another
sort of usefulness, in its way.
> >> - documenting Packages
> > There definitely need to be provisions for that.
> erm ... we already have __init__.py, so a __doc__.py might be cool ?
> Possibly alongside __doc__.stng or some such containing the ref docs ?
I would say that the package docstring is the docstring in __init__.py.
I would probably avoid having a __doc__.<whatever> file, 'cos I wouldn't
be able to guess exactly what it was for. And I've been using ".stx" for
an extension, in compatibilty with STClassic and STNG - but maybe we
*should* be using different extensions for different files.
I hereby propose:
'.stx' -- the file contains text compatible with either
STClassic or, more usefully, STminus
'.stng' -- the file contains STNG text. It may or may not
be parsable by ST<other> parsers
'.stpy' -- the same position for STpy text
Is this worth "formalising" by also posting it onto the ZWiki? Or is it
just overcomplex? Is it a bad thing we've lost any reference to "tx" in
the string?
Eddy then wandered off into the paragraph labels debate:
> While I'm at it: I loathe and despise the apparent demand
> (seemingly from both schools - Tibs: does your form require
> the space between the Author and Version lines ?) for blank
> lines in various places which feel (to me) just plain wrong;
> I want to write (descriptive lists and, in particular, ...)
> the Edward-form of the last as
>
> Document information
> Author -- Guido
> Version -- 3.14
>
> A random paragraph which isn't a sub-paragraph of the
> document information.
>
> and believe I shall not be alone (among python programmers) in
> tending to neglect those blank lines (in *all* descriptive lists)
> and being irritated by any tool which insists on me adding them.
> Gratuitous whitespace `halves' the amount of information I can
> fit in front of my eyeballs at a given moment and that *matters*
> to the *maintainability* of my code - an issue which I take very
> seriously.
Hmm - I'm well aware of how far Eddy will take the elision of vertical
whitespace to keep stuff compact.
Strangely enough, the example Eddy gives (in Edward form) *is*
legitimate STpy, since the list items start new paragraphs. If it were
cast in my form:
Document information
Author: Guido
Verision: 3.14
then it doesn't work, since labelled paragraphs don't start a new
paragraph.
For the moment, tough. However, I do tend to share the view that this is
unnatural - I *think* that most people will expect the above to work,
because that "word followed by colon" thingy is something we're used to.
Unfortunately, to integrate new paragraphs starting on these things into
the code in a neat manner is more than ten minutes work, and there are
more important things to do for the alpha release. I think this is the
sort of issue that should be raised thereafter, in discussion of the
PEP, and I would certainly support changing the code if there were
agreement on this issue (heh, I'm aiming at 2.2 now, since 2.1 is
obviously hopelessly soon, so the pressure is off a bit).
> Given the choice between
> pandering to the tastes of a tool for extracting
> the documents and
> being kind to the poor sod who has to maintain the code
> I am typically going to side with the latter
Oh yes, me too (it's just a matter of lack of time - firstly for coding,
and secondly for convincing myself that *yet another* special case isn't
one too many for the STpy mindspace - I kid myself I'm getting a feel
for ST-zen, and want to *know* things fit in well).
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.)