[Doc-SIG] two simple, but important questions
Tony J Ibbs (Tibs)
tony@lsl.co.uk
Wed, 14 Mar 2001 10:43:01 -0000
Tavis Rudd (who is being very patient with us jumping up and down on his
arguments) wrote:
> 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
Ah - not a problem. In the current world, you just explain them in the
class/module docstring (not a bad thing). In MAL's proposal, you add new
docstrings AFTER each value's default setting.
So old scheme would have::
class Useful:
"""A really useful class.
There are two class variables defined:
#name# -- the name of something or other
#number# -- its quantity
"""
# Let's have some default values for those
name = "Fred"
number = 9
and the new scheme would (I believe) have::
class Useful:
"""A really useful class.
(and I'd maybe *still* have some reference in the
class docstring to the class values)
"""
name = "Fred"
"""#name# is the name of something or other"""
number = 9
"""#number# is its quantity"""
> - 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??)
Let's assume not - people can always strip stuff out with -o if they
want.
> - a means to include the Library reference documentation in
> the same file, as
> Ping proposed
Which is, let us say, hotly debated.
> 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.
Ooh, I saw you do that.
No, allowing people to do something I don't want them to be able to do,
on the grounds they might not do it, isn't what I want (see, at heart I
want to be part of the PSU (erm, I didn't say that)).
Tibs (who also has odd names)
--
Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/
Well we're safe now....thank God we're in a bowling alley.
- Big Bob (J.T. Walsh) in "Pleasantville"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)