[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Help-smalltalk] Documentation syntax
From: |
Mike Anderson |
Subject: |
Re: [Help-smalltalk] Documentation syntax |
Date: |
Wed, 16 Aug 2006 16:13:54 +0000 |
User-agent: |
Mozilla Thunderbird 1.0.5 (X11/20050711) |
Bram Neijt wrote:
> Hi Smalltalk users,
>
> I'm hoping to create an online documentation system which can be
> exported/spliced into the source when needed and vice-versa. Because
> we only have one documentation comment block per function, we need
> extra syntax to allow the defenition of arguments etc.
I don't really know what you mean by "an online documentation system",
so I might still be persuaded, but I don't really see the need for the
markup.
Take this method:
PositionableStream >> copyFrom: start to: end
"Answer the collection on which the receiver is streaming, from
the start-th item to the end-th"
^collection copyFrom: start to: end
Arguably, this comment doesn't tell us anything that isn't self-evident,
but anyway, how would you mark it up so that it gives us more information?
> Some of these syntaxes are:
> - @-sign (e.g. @return, @arg hello The hello argument)
> - \-sign (same but a \ instead of @
> - XML
> - HTML
>
> Both XML and HTML give to much overhead in my opinion, so those seem
> stupid.
> Furthermore, the \-sign is already an escape character, so that might
> also be a problem. However, the @ sign requires the use of the SHIFT
> key.
\ isn't an escape character in Smalltalk.
Regards,
Mike
- [Help-smalltalk] Documentation syntax, Bram Neijt, 2006/08/15
- Re: [Help-smalltalk] Documentation syntax,
Mike Anderson <=
- Re: [Help-smalltalk] Documentation syntax, Paolo Bonzini, 2006/08/16
- Re: [Help-smalltalk] Documentation syntax, Bram Neijt, 2006/08/16
- Re: [Help-smalltalk] Documentation syntax, Brian Brown, 2006/08/16
- Re: [Help-smalltalk] Documentation syntax, Mike Anderson, 2006/08/16
- Re: [Help-smalltalk] Documentation syntax, Paolo Bonzini, 2006/08/17
- Re: [Help-smalltalk] Documentation syntax, Stewart Stremler, 2006/08/17
- Re: [Help-smalltalk] Documentation syntax, Bram Neijt, 2006/08/19
- Re: [Help-smalltalk] Documentation syntax, Mike Anderson, 2006/08/19
- Re: [Help-smalltalk] Documentation syntax, Mike Anderson, 2006/08/19