Re: [Help-smalltalk] Documentation syntax

[Brian Brown]

A bit off topic...

I use Squeak a lot, and one of the things that is really lacking in  
Smalltalk documentation methods is the idea of a  package level  
document, not just class and method, which work fine.  One of the  
frustrating things is looking at many, many classes and not having  
any pointers as which class would be used for what purpose, etc. A  
package level doc facility would alleviate this.  I don't know enough  
about gst yet to know if it has such a facility.

My .02

Brian

On Aug 16, 2006, at 11:49 AM, Bram Neijt wrote:

> Hi Mike and Paolo (and other readers),
>
> 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.
>
> My logic behind wanting markup was actually driven by my desire to
> build a community driven wiki like documentation system for GNU
> Smalltalk.
>
> 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.)
>
> On 8/16/06, Paolo Bonzini <address@hidden> wrote:
> > I believe that this could help the readability of the manual--OTOH it
> > would hinder the readability of the source code.  Maybe we need a
> > simpler coding, like
> This is a very valid point, if any markup is chosen it should keep the
> code comments readable. However, the markup (just to be clear) is not
> ment for things like "emphasis", this was not what I ment. IMHO it
> should only point out which parts are special (variable names, class
> names) or bind information to an entity (like HTML definition lists
> (DL)).
>
> 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
>
> But we have the freedom to choose whatever fits Smalltalk best :-D
>
> Well, that probably raised enough questions/comments.
>
> Thanks for the responses,
>  Bram
>
>
> _______________________________________________
> help-smalltalk mailing list
> address@hidden
> http://lists.gnu.org/mailman/listinfo/help-smalltalk