Re: [Help-smalltalk] Documentation syntax

[Paolo Bonzini]

Mike Anderson wrote:
> > I can see why an online documentation system doesn't seem needed. And
> > the short awnser is: it isn't. Smalltalk was designed to be used while
> > working in the system, like Squeak (as far as I can see). So all
> > documentation can be done with a browser/viewer within the virtual
> > machine.
> >     
> On the contrary: when I first started learning (GNU) Smalltalk, I
> referred to the generated HTML docs extensively. In addition, having to
> install a package in order to find out anything about it is something I
> find very off-putting about other-dialect packages. I'm sure that the
> same is true of GSt.
>   
More so, since the browser is not the main development environment 
(which is not going to change anytime soon).
> > The Javadoc/doxygen method is:
> > PositionableStream >> copyFrom: start to: end
> >    "Answer the collection on which the receiver is streaming, from
> >      the start-th item to the end-th
> >    @arg start The starting position
> >    @arg end The ending position
> >    @see Smalltalk.Collection
> >    "
> >     ^collection copyFrom: start to: end
> >     
> OK, but the method is now five lines of comment and one of code, and
> arguably didn't need the two lines of comment that it started with.
>   
Yep.  They're only there for the sake of documentation generation, not 
because a code reader would need them.
> What I was getting that was that, if you have "copyFrom: start to: end",
> and you also have "from the start-th item to the end-th", what
> additional information are you getting from "@arg start The starting
> position" and "@arg end The ending position" ?
>   
Nothing :-)  But I still think it would add something to have @{start} 
and @{end} show up in a different font.  And bonus points if you can get 
ASCII "markup" like "_Do not_ do this" into formatting markup.
> Also, if "Answer the collection" was written "Answer the Collection",
> then Collection could be made into a link without adding any markup.
>   
That's true.

Paolo