[Newbies] Smalltalk klass dokumentation ?

[Kommentaren]

Well, I take this to mean you do not know about any decent documentation for 
Smalltalk classes?

>  Like javadoc, people have built extraction tools. Few people use them and 
> the extracted comments rapidly fall out of date.

This just is NOT so. Javadoc was and is the brilliant idea to put the 
documentation in the code so that it could be easily updated.

The documentation you get from javadoc is easily regenerated by running a 
standard utility - or directly from a GUI. The amounty of javadoc can be as 
high as 50% of the total code.
That is half is code and half is documentation.

The utility you run also parses the code and will give you a lot of 
important extra information such as information about hierachy structures 
superclasses, subclasses, summaries, etc etc.

I have worked for several decades with java, QA, methods, testing, etc etc 
and there is no professional java programmer that does not use javadoc.
In fact, when you get to a new java project the first thing you do is go 
looking for any javadoc because that is often the only documentation that 
you can find.

(When it comes to base classes there are of course plety of supplementary 
documentation.)

Thus, when I started to look att Smalltalk again and did not - and perhaps 
does not still understand - some code I go looking for documentation.

[I looked at Smalltalk in the early 90:ties and fell in love with it but 
could get no consulting job in it so I left it.]

Java has been a great success even though it came later than Smalltalk. One 
key question is - why?

Could lack of good systematic documentation be one of the reasons?





----- Original Message ----- 
From: "David Mitchell" <david.mitchell at gmail.com>
To: "A friendly place to get answers to even the most basic questions 
aboutSqueak." <beginners at lists.squeakfoundation.org>
Sent: Tuesday, May 11, 2010 4:30 PM
Subject: Re: [Newbies] Smalltalk klass dokumentation ?


The hard part is writing the comments. Not the tools. We do have
tools, though...

The "like Javadoc" part is the class comments and method comments.

Click the ? between class and instance for the class you are interested in.

Unlike javadoc, there is no practice of inserting markup into
comments. There is capability of RichText, but I haven't seen anyone
use that since the 1990s. Plain text rules the day.

Like javadoc, people have built extraction tools. Few people use them
and the extracted comments rapidly fall out of date.

Like nearly all documentation, the comments rapidly fall out of date
in Smalltalk too.

You can write new comments and commit them. Search squeak-dev or the
wiki for documentation and you'll see lots of prior projects in this
space.



On Tue, May 11, 2010 at 5:46 AM, Kommentaren <kommentaren at bredband.net> 
wrote:
> Hi!
>
> I wonder if there is any documentation that documents the different 
> classes
> and methods available in Smalltalk. Preferably like javadoc in java.
>
> For example, somewhere you could go when you want to understand a code 
> like
> the following (taken from the Laser-game tutorial at squeak).
>
>
>
> panel := RectangleMorph new borderWidth: 0;
>
> color: Color white;
>
> layoutPolicy: ProportionalLayout new.
>
>
>
>
>
> panel
>
> addMorph: self makeQuitGameButton
>
> fullFrame:
>
> (LayoutFrame
>
> fractions: (0 at 1 corner: 1 at 1)
>
> offsets: (
>
> (20 @ (vertOffsetTop negated))
>
> corner: (-20 @ (vertOffsetBtm negated)))).
>
>
>
>
> That is, you make a panel using the ProportionalLayout and then you add
> buttons to it. Here you need to know what the ProportionalLayout is and 
> how
> the fractions and offsets parameters work
> to understand how the buttons are placed.
>
>
>
>
>
> _______________________________________________
> Beginners mailing list
> Beginners at lists.squeakfoundation.org
> http://lists.squeakfoundation.org/mailman/listinfo/beginners
>
>
_______________________________________________
Beginners mailing list
Beginners at lists.squeakfoundation.org
http://lists.squeakfoundation.org/mailman/listinfo/beginners