[Newbies] Smalltalk klass dokumentation ?

Wed May 12 07:37:28 UTC 2010

Hi,
On 12.05.2010, at 00:05, Kommentaren wrote:

> 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.
> 
That's right there is nothing magic about extracting javadoc. The tool even is that good that you can generate source stubs from javadoc. I experienced once that we only got the javadoc from which we built the stubs to implement against. Not too bad but seldomly used.

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

It would be a good idea to leave out those kind of sentences if you don't want to raise tension.  We all know that you didn't work "several decades" with java :) And stating that you have decades of experience in this area doesn't make your statements "more true". It will be still what you write that is good or not.

I can't agree on your statement that there aren't professional java programmers that don't use javadoc. Quite the opposite in my experience. To me it appears this way: Documentation is only properly created if the source code is build for a customer. In this case the documentation is part of a contract. I didn't see that much documentation that was created by a developer out of his own motivation to do so.

> 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.
> 
That is a fundamental difference if you are talking about documentation. In lanaguages like java you need to have documentation because you ususally don't have the code. So I would state that people programming java are forced to create more documentation which isn't that bad. 

> (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.
> 
And it is bad if can't find one. This I can fully understand. I myself do not tend to overestimate the use of documentation. To be honest I consider documentation a bad thing for now and then. But if you have the code and the code does not explain itself than you are in need of a proper documentation. To me that's _the_ definition of useful documentation. 
We know that this is a part that needs improvement. But it also needs people that are willing to do it because it is still open source. Are you willing to add documentation that you consider "is missing"?? 

> [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.]
> 
Sometimes you need to create those jobs as well. Otherwise you are forced to swim where the water flows :)

> 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?
> 
Well, who knows? To me java had good marketing ideas at the right time. This thing that enables you to write programs that run in every browser (you remember applets) was a good one. Followed by that thing that enables you to write cross-platform GUIs. Followed by the languages that deals with unicode and XML. Followed by EJB specification. etc. You name it. 
The very important rest is that they created a rich set of industrial grade APIs to deal with every single topic that emerged into this new medium network/internet. And that makes java a good language to solve problems.

my 2 cents,

Norbert

> 
> 
> 
> 
> ----- 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 
> _______________________________________________
> Beginners mailing list
> Beginners at lists.squeakfoundation.org
> http://lists.squeakfoundation.org/mailman/listinfo/beginners

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.squeakfoundation.org/pipermail/beginners/attachments/20100512/65a87f37/attachment-0001.htm