Smalltalk klass dokumentation ?
Locked
 
|
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@1 corner: 1@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 [hidden email] http://lists.squeakfoundation.org/mailman/listinfo/beginners |
Re: 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 <[hidden email]> 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@1 corner: 1@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 > [hidden email] > http://lists.squeakfoundation.org/mailman/listinfo/beginners > > Beginners mailing list [hidden email] http://lists.squeakfoundation.org/mailman/listinfo/beginners |
Re: Smalltalk klass dokumentation ?
|
|
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" <[hidden email]> To: "A friendly place to get answers to even the most basic questions aboutSqueak." <[hidden email]> 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 <[hidden email]> 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@1 corner: 1@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 > [hidden email] > http://lists.squeakfoundation.org/mailman/listinfo/beginners > > Beginners mailing list [hidden email] http://lists.squeakfoundation.org/mailman/listinfo/beginners _______________________________________________ Beginners mailing list [hidden email] http://lists.squeakfoundation.org/mailman/listinfo/beginners |
[OT] Re: [Newbies] Smalltalk klass dokumentation ?
|
|
Am 11.05.2010 um 15:05 schrieb Kommentaren:
> > I have worked for several decades with java O RLY? ;) > Java has been a great success even though it came later than Smalltalk. One key question is - why? Money, and catering to average managers of mediocre programmers. (And before you get too upset: I did not say everyone and everything related to Java is bad, but simply that targeting that crowd made Java so successful) - Bert - _______________________________________________ Beginners mailing list [hidden email] http://lists.squeakfoundation.org/mailman/listinfo/beginners |
Re: [OT] Re: [Newbies] Smalltalk klass dokumentation ?
|
|
I can't get angry with an explanation that is no explanation. Just smile :-)
And before you get mad, just let me tell you that I love Smalltalk too. But loving someone should not make us blind if that hurts the loved one? Huh? > O RLY? ;) I prefer Smalltalk when expressing my ideas/programming to Ada, Simula, Basic (yes I am old) Pascal, EriPascal, Cobol (Well, Cobol when used for what it was intended for is not to bad really), Fortran, C, assembler, ETC, and of course Java. Have tried to stay away from C++ though. I have even developed a language and interpreter myself used for testing mobile phones. And so on. Your reaction reminds me of a manager I once worked under - Oh yes we had this great programmer. Really bright! However, when he changed work we had to throw away his code though and start from scracth because nobody could understand his code. . . But he was bright my manager said. Really I say? Documentation is important. Sun knows what they are doing. ----- Original Message ----- From: "Bert Freudenberg" <[hidden email]> To: "A friendly place to get answers to even the most basic questions aboutSqueak." <[hidden email]> Sent: Wednesday, May 12, 2010 12:20 AM Subject: [OT] Re: [Newbies] Smalltalk klass dokumentation ? Am 11.05.2010 um 15:05 schrieb Kommentaren: > > I have worked for several decades with java O RLY? ;) > Java has been a great success even though it came later than Smalltalk. > One key question is - why? Money, and catering to average managers of mediocre programmers. (And before you get too upset: I did not say everyone and everything related to Java is bad, but simply that targeting that crowd made Java so successful) - Bert - _______________________________________________ Beginners mailing list [hidden email] http://lists.squeakfoundation.org/mailman/listinfo/beginners _______________________________________________ Beginners mailing list [hidden email] http://lists.squeakfoundation.org/mailman/listinfo/beginners |
Re: [OT] Re: [Newbies] Smalltalk klass dokumentation ?
|
|
>>>>> "Kommentaren" == Kommentaren <[hidden email]> writes:
Kommentaren> Documentation is important. Agreed. Which is why it's so easy to create class comments, and method comments, and browse/search those comments *while* you are using the code. We don't need dead trees or static docs. We want docs that are as alive as the code is. Kommentaren> Sun knows what they are doing. Hardly. Sun doesn't even exist anymore. How "knowing" is that? -- Randal L. Schwartz - Stonehenge Consulting Services, Inc. - +1 503 777 0095 <[hidden email]> <URL:http://www.stonehenge.com/merlyn/> Smalltalk/Perl/Unix consulting, Technical writing, Comedy, etc. etc. See http://methodsandmessages.vox.com/ for Smalltalk and Seaside discussion _______________________________________________ Beginners mailing list [hidden email] http://lists.squeakfoundation.org/mailman/listinfo/beginners |
Re: [OT] Re: [Newbies] Smalltalk klass dokumentation ?
|
|
Java was and still is a success no matter how you put it.
Coming up with class comments for Squeak is a hard job because it involves a lot of design recovery. Comments are supposed to generalise code details in a language which is easy to understand. The challenge is not talking about these things as they are pretty obvious. Actually writing comments is a challenge. As soon as you start digging into it you realise that there is _a lot_ to do. The task is rather daunting. --Hannes On 5/11/10, Randal L. Schwartz <[hidden email]> wrote: >>>>>> "Kommentaren" == Kommentaren <[hidden email]> writes: > > Kommentaren> Documentation is important. > > Agreed. Which is why it's so easy to create class comments, and method > comments, and browse/search those comments *while* you are using the > code. > > We don't need dead trees or static docs. We want docs that are as alive > as the code is. > > Kommentaren> Sun knows what they are doing. > > Hardly. Sun doesn't even exist anymore. How "knowing" is that? > > -- > Randal L. Schwartz - Stonehenge Consulting Services, Inc. - +1 503 777 0095 > <[hidden email]> <URL:http://www.stonehenge.com/merlyn/> > Smalltalk/Perl/Unix consulting, Technical writing, Comedy, etc. etc. > See http://methodsandmessages.vox.com/ for Smalltalk and Seaside discussion > _______________________________________________ > Beginners mailing list > [hidden email] > http://lists.squeakfoundation.org/mailman/listinfo/beginners > Beginners mailing list [hidden email] http://lists.squeakfoundation.org/mailman/listinfo/beginners |
Re: [OT] Re: [Newbies] Smalltalk klass dokumentation ?
|
|
>>>>> "Hannes" == Hannes Hirzel <[hidden email]> writes:
Hannes> Coming up with class comments for Squeak is a hard job because it Hannes> involves a lot of design recovery. And that's completely unrelated to the problem at hand. The original question seems to be "why isn't there javadoc for Smalltalk"? My reply is "Javadoc sucks compared to Smalltalk's embedded tools." Don't confuse that with the issue that the current *image* is probably underdocumented. -- Randal L. Schwartz - Stonehenge Consulting Services, Inc. - +1 503 777 0095 <[hidden email]> <URL:http://www.stonehenge.com/merlyn/> Smalltalk/Perl/Unix consulting, Technical writing, Comedy, etc. etc. See http://methodsandmessages.vox.com/ for Smalltalk and Seaside discussion _______________________________________________ Beginners mailing list [hidden email] http://lists.squeakfoundation.org/mailman/listinfo/beginners |
Re: [OT] Re: [Newbies] Smalltalk klass dokumentation ?
|
|
On Tue, May 11, 2010 at 06:44:50PM -0700, Randal L. Schwartz wrote:
> >>>>> "Hannes" == Hannes Hirzel <[hidden email]> writes: > > Hannes> Coming up with class comments for Squeak is a hard job because it > Hannes> involves a lot of design recovery. > > And that's completely unrelated to the problem at hand. > > The original question seems to be "why isn't there javadoc for > Smalltalk"? Actually, the original question was this: "I wonder if there is any documentation that documents the different classes and methods available in Smalltalk. Preferably like javadoc in java." So I think that Hannes' response is exactly right. But of course you are also right that Smalltalk's embedded tools are exceptional, and they can also be used to generate documentation for external viewers such as this particularly cool example: http://www.mobilewikiserver.com/SqueakDocs.html Dave _______________________________________________ Beginners mailing list [hidden email] http://lists.squeakfoundation.org/mailman/listinfo/beginners |
Re: [OT] Re: [Newbies] Smalltalk klass dokumentation ?
|
|
>>>>> "David" == David T Lewis <[hidden email]> writes:
David> Actually, the original question was this: David> "I wonder if there is any documentation that documents the David> different classes and methods available in Smalltalk. Preferably David> like javadoc in java." Right, and the answer to this is "Yes, *inside the image*, which makes it nicely searchable and maintainable, although the current image lacks adequate documentation. And thank goodness this is nothing like Javadoc." -- Randal L. Schwartz - Stonehenge Consulting Services, Inc. - +1 503 777 0095 <[hidden email]> <URL:http://www.stonehenge.com/merlyn/> Smalltalk/Perl/Unix consulting, Technical writing, Comedy, etc. etc. See http://methodsandmessages.vox.com/ for Smalltalk and Seaside discussion _______________________________________________ Beginners mailing list [hidden email] http://lists.squeakfoundation.org/mailman/listinfo/beginners |
Re: Smalltalk klass dokumentation ?
|
|
In reply to this post by Kommentaren
Hi,
On 12.05.2010, at 00:05, Kommentaren wrote: 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.
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. 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. 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"?? Sometimes you need to create those jobs as well. Otherwise you are forced to swim where the water flows :) 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
_______________________________________________ Beginners mailing list [hidden email] http://lists.squeakfoundation.org/mailman/listinfo/beginners |
Re: Smalltalk klass dokumentation ?
|
|
In reply to this post by Kommentaren
> 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. Listen, I'm not disparaging Java nor Javadoc. I've done professional Smalltalk and Java since 1995. Prior to that, I was a professional technical writer. I always deliver Javadoc (and I always write class and method comments in Squeak). The process for *writing* comments is essentially the same. > 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? Oh sure, but there are more reasons than just that. Smalltalk isn't Java. It's different. Lots of Java open source tools are really underwritten by major corporations. Very few Smalltalk efforts have such underwriting. When IBM had hundreds of coders and technical writers working on Smalltalk rather than Java, the quality and volume of Smalltalk doc was higher. Cincom Smalltalk still follows this practice (but they aren't open source). Cincom has outstanding doc (and an amazing library of videos). Consider this: Squeak has a facility for writing comments and hyperlinking them. You can browse the comments in Squeak. People have built tools like the javadoc tool for Squeak to extract the comments and turn them into HTML. Here is the result of someone's work: http://www.oldenbuettel.de/squeak-doku/ST80-Paths/Arc.html Now, that looks a lot like Javadoc! So now the question is. Other people have built the Javadoc infrastructure for squeak. But no one took up the cause. Why? I believe there is a new documentation team forming. You may want to subscribe to squeak-dev and ask about it. _______________________________________________ Beginners mailing list [hidden email] http://lists.squeakfoundation.org/mailman/listinfo/beginners |
«
Return to Squeak - Beginners
|
1 view|%1 views
| Free forum by Nabble | Edit this page |