[Doc-SIG] Re: docstring signatures

M.-A. Lemburg mal@lemburg.com
Sun, 25 Mar 2001 15:35:21 +0200

"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

  * 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/