Re: [Help-smalltalk] Documentation syntax

[Stewart Stremler]

begin  quoting Paolo Bonzini as of Thu, Aug 17, 2006 at 08:52:24AM +0200:
> Mike Anderson wrote:
[snip]
> >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).

As many of us rely heavily on the HTML documentation, perhaps we could
look at the deficiences there, and come up with what we'd like in an
automated-document-generator...

Elsethread it was recommended that we have package-level documentation,
which I thing would be pretty useful as well.

A parent- and child-hierarchy and a used-by list would be on my wishlist.

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

The document writer could put in type hints for the document reader,
as the document reader needs more information than the code reader...

  " ...
  @arg start a {Number} not less than 0 indicating the start position.
  @arg end a {Number} not less than _start_ indicating the end position.
    ..."

(Mabye type-hints? e.g. "@arg Number start ...." -- but that feels
like it would go terribly wrong...)

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

Standard usenet (and some wiki) markup rules?  *Strong*, /emphasize/
or _emphasize_, etc.?  Yes, that would be nice. 

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

Markup would be needed to un-select inappropriate links. If I have
a class named "Answer", it shouldn't be linked to everytime someone
writes "Answer the blah-blah-blah", as it would be unrelated, and
the resulting link would be confusing.

-- 
Stewart Stremler