[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.