[Doc-SIG] Re: docstring signatures

[M.-A. Lemburg]

"Edward D. Loper" wrote:
> 
> > Don't spend too much time trying to make StructuredText or some
> > variation thereof work.  In my experience with systems that use ST
> > (like ZWiki), it sucks.  There basically are two options I like:
> > nicely laid out plain text, or a real markup language like Latex or
> > DocBook.

ST may suck, but it still provides a good compromise between
readable source code level documentation and a machine
parseable format.

Just for reference, here's part of a javadoc-string with real
markup:

/**
  * Constructs a <code>BigDecimal</code> object from a
  * <code>BigInteger</code>, with scale 0.
  * <p>
  * Constructs a <code>BigDecimal</code> which is the exact decimal
  * representation of the <code>BigInteger</code>, with a scale of
  * zero.
  * The value of the <code>BigDecimal</code> is identical to the value
  * of the <code>BigInteger</code>.
  * The parameter must not be <code>null</code>.
  * <p>
  * The <code>BigDecimal</code> will contain only decimal digits,
  * prefixed with a leading minus sign (hyphen) if the
  * <code>BigInteger</code> is negative.  A leading zero will be
  * present only if the <code>BigInteger</code> is zero.
  *
  * @param bi The <code>BigInteger</code> to be converted.
  */

Python doc-string should maintain the same level of elegance
as the rest of the language, IMHO.

> >
> > --Guido van Rossum (home page: http://www.python.org/~guido/)
> 
> Hm.  I guess I should have thought to ask the BDFL about all this
> before now. :)  Makes me wonder if he'll like/accpet *any* of the
> stuff we've been talking about.  But it's interesting to hear
> that Guido is ok with a real markup language.
> 
> So are there any vocal opponents of using a real markup language
> on doc-sig right now?  (Assuming that Guido doesn't want us
> to use something like ST)..

Here's one ;-)

-- 
Marc-Andre Lemburg
______________________________________________________________________
Company & Consulting:                           http://www.egenix.com/
Python Pages:                           http://www.lemburg.com/python/