[Doc-SIG] Re: docstring signatures

[Tony J Ibbs (Tibs)]

Greg Ward wrote:
> I've been lurking throughout this whole thread (and
> occasionally leaning on the "D" key... sorry guys... ;-)

no, sounds sensible to me - I hate to think what it must "sound" like to
anyone else listening to our, erm, interchanges.

> However, I would just like to state for the record that I am
> not -0, or -1, but more like -1e6 on putting a "real" markup
> language in docstrings, assuming that the set of "real" markup
> languages is limited to {Tex-like languages, SGML-like languages}.

Well, I think that's taken to be the general meaning of "real" in this
sort of context. These days, in this forum, I prefer the term
"heavyweight".

> I consider both to be misbegotten freaks
> that completely ignore the human factors
> of writeability and readability.

Ah - but they are "misbegotten freaks" that *deliberately* ignore the
human factors of etc.

TeX because it was originally aimed at people with great motivation to
use it for its original purposes (and when there was no alternative),
but not *really* for "human beings" in the aggregate.

SGML/XML/etc because they're not meant for humans to read/write. Despite
the fact some of us do.

Personally, I used to be +10 for formal markup, but am now (somewhat
reluctantly) -1 against it (see, my response got more moderate!).

> Larry Wall has been there and done that: "man perlpod" if you're on a
> properly administered Unix system.  ;-)

Hmm. Actually, our sysadmin really likes perl. And he's a friend.

> POD is really easy to write, and
> pretty easy to read (human) and parse (software).

Hmm. Personally I think it has all the disadvantages for reading that
things like XML do, but with none of the advantages of *being* something
like XML. Of course, reactions differ.

> Althought I've never used ST, my understanding is that ST and
> POD are pretty semantically similar, and with very similar goals:
> easy-to-write, easy-to-read, minimal markup that's "good enough" for
> generating man pages, HTML documents, and plain text.

Probably so - they're doubtless as similar as Perl and Python (which is
quite similar, of course, compared to many other languages).

> They both suffer from lack of
> formalization, although I think POD is better nowadays.

And if Edward Loper finishes his task (heh, even if I finish mine) will
be a lot better for STpy too.

> XML is many things to many people, but it most
> certainly is not fit for human consumption.

It would be amazing if it were - I'm currently working with (well,
thinking about, some of the time) *quite large* XML documents (well,
actually, they represent geographic data) and one would be surprised if
a human ever tried to look at it.

> OTOH, I quite like Javadoc's "@param", "@return" syntax.
> It's easy to write, easy to read, easy to parse, and just
> formal enough so that doc tools can make sense of it.
> It might be more Pythonic to spell those "param:",
> "returns:", though.  ;-)

Erm, "Arguments:" and "Returns:" (the last is an "I think", 'cos I don't
tend to use it)

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Give a pedant an inch and they'll take 25.4mm
(once they've established you're talking a post-1959 inch, of course)
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)