[Doc-SIG] PEP-0216

[Tony J Ibbs (Tibs)]

Mark Hammond worries about Moshe's (a) and (b) points in the PEP...
> > >From the PEP, it seems you may be thinking about situations like:
> >
> > """ ... the POP3() class is passed as a parameter, and the result
> > is an rfc822.Message() instance ..."""

It has been said for a long time that we need to be able to generate
cross-references from the docstring to the actual code, which is what this
is about.

HOWEVER. It seems clear to me that we deal with the things we can do now
(more or less!) first (i.e., points d and e). Point c is debatably covered
(via the Example or :: conventions). We can live with it for the moment.
Points a and b are desirable, but we can live without them in the first
instance if it means we get DOCUMENTATION started (which is, after all, the
*most* important thing).

It looks like StructuredTextNG is meant to be designed so it can be
"subclassed" for other purposes - at least that's a stated aim. So I would
expect the Zopistas to be willing to help us get such a subclassing going,
and that's clearly the way to handle the additional points. And if it's done
via subclassing, we can clearly roll it in later on.

BTW, I commend the following page to people:

http://www.zope.org/Members/jim/StructuredTextWiki/StructuredTextZen

I'm not entirely sure I agree, but then I wouldn't be...

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