[Doc-SIG] Re: docstring signatures
Edward Welbourne
Edward Welbourne <eddy@chaos.org.uk>
Sat, 31 Mar 2001 16:21:33 +0100 (BST)
> (incidentally, this use is the main reason that I support DLs in
> documentation strings..)
and your other illustration,
> argument x: description of x
> throw y: description of y
would make a good alternative way to approach DLs, even if only as:
item a: description of a
item b: and so on
with item being some base label whose meaning is specialised by argument
and throw.
Though I must say I prefer the -- form, albeit maybe modified to use
some other punctuator for the sake of folk like Guido who've picked up
(let me guess -- from writing TeX ?) the habit of using -- as en-dash,
so as to reserve - for hyphen (and minus). But note that TeXies might
well also use --- (for em-dash, naturally) and it gets a bit excessive
to go to ----. How about -: or some similar punctuator, maybe -:- would
do ? Or ~~ or @: or @- etc. It needs to `feel' right and not be in
common use. Arguably .. would be good, or :: appearing *not* at the end
of a line.
Of course what would be ideal must surely be some sort of mimic of the
lexical structure of dictionaries, { key: value, yek: eulav }, though
how to parody that into a form suitable for ST I can't say.
Eddy.