[Newbies] Smalltalk klass dokumentation ?
Kommentaren
kommentaren at bredband.net
Tue May 11 22:05:27 UTC 2010
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
More information about the Beginners
mailing list