[Doc-SIG] Re: docstring signatures

[Greg Ward]

On 26 March 2001, Tony J Ibbs (Tibs) said:
> > 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.

The differences are subtle, but they're enough: in POD, tags are shorter
(one character), only used intra-paragraph (ie. there aren't tags for
sections or indented code chunks -- that's more-or-less implicit), and
there's far less tendency to nest them.  That makes a *huge* difference for
human readability/writeability.

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

Yup.  In my fairly uninformed opinion, it seems like the main differene
between POD and ST is spelling.  One uses B<bold> and C<code>, the other
uses *bold* and 'code'.  I prefer POD's slightly more in-your-face and less
ambiguous markup, but that's mainly because I have experience with it and I
know I like it.  I'm sure I could come to like ST in time, too.  ;-)

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

More trivial spelling differences.  I don't much care how it's spelled, but
I like the idea of a tiny bit of formal markup to say, "this is a function
return value", "this is a function argument", "this is an instance
attribute", "this is a class attribute", etc.  Trailing colon is definitely
more Pythonic than leading "@", though!

        Greg