[Doc-SIG] Additional docstrings

Tony J Ibbs (Tibs) tony@lsl.co.uk
Wed, 8 Aug 2001 10:00:22 +0100

David Goodger wrote:
> I think the use of docstrings as metadata is dying out, now that we
> have function attributes. I included additional docstrings as a
> mechanism to reduce runtime usage for voluminous documentation.
> They're not an absolute requirement though: easy to drop, and easy to
> put off until later.
> Sorry, I'm not convinced. Do we really need to identify additional
> docstrings? Can you come up with a convincing rationale? And then, a
> good way of identifying them.

Unfortunately, I think it will be around for a while. Zope has legacy
reasons, and (sorry, forgot his name) who does one of the parses was
arguing heavily some while back that he *wants* to put his parsing info
in a docstring. This last didn't look like it would go away - he did
*not* like the fact that using a function attribute meant an assignment,
and one that has to come after the function at that (it is not visually
associated with the function at all well).

On the other hand, we may be able to put off worrying about this for the
moment - and the chances of one entity wanting more than *two*
docstrings is hopefully remote.


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