[Doc-SIG] two simple, but important questions

[Tony J Ibbs (Tibs)]

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.)