Re: [Help-smalltalk] Documentation syntax

[Mike Anderson]

Bram Neijt 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.

> Common documentation systems include things like: examples, verbose
> argument explanaition, return value and type explenation, possibly
> TODO's, a 'see also' list, links, class variable documentation, etc.
>
> So to awnser the question 'what, if anything, would a markup add?':
> one or more of the above (as needs be ;-) ). (Keep in mind that this
> didn't start because of a lack of documetation or it's quality: simply
> because I would like a wiki system with that same markup.)

It seems to me that all of the additional information that is worth
having is either a link or a link in disguise.

[chopping up the replies - I hope this doesn't offend anybody]

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

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" ?

Also, if "Answer the collection" was written "Answer the Collection",
then Collection could be made into a link without adding any markup.

Mike