Re: [Help-smalltalk] Documentation syntax

[Mike Anderson]

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