Smalltalk klass dokumentation ?

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
12 messages Options
Reply | Threaded
Open this post in threaded view
|

Smalltalk klass dokumentation ?

Kommentaren
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
Reply | Threaded
Open this post in threaded view
|

Re: Smalltalk klass dokumentation ?

David Mitchell-10
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
Reply | Threaded
Open this post in threaded view
|

Re: 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" <[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
Reply | Threaded
Open this post in threaded view
|

[OT] Re: [Newbies] Smalltalk klass dokumentation ?

Bert Freudenberg
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
Reply | Threaded
Open this post in threaded view
|

Re: [OT] Re: [Newbies] Smalltalk klass dokumentation ?

Kommentaren
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
Reply | Threaded
Open this post in threaded view
|

Re: [OT] Re: [Newbies] Smalltalk klass dokumentation ?

Randal L. Schwartz
>>>>> "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
Reply | Threaded
Open this post in threaded view
|

Re: [OT] Re: [Newbies] Smalltalk klass dokumentation ?

Hannes Hirzel
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
Reply | Threaded
Open this post in threaded view
|

Re: [OT] Re: [Newbies] Smalltalk klass dokumentation ?

Randal L. Schwartz
>>>>> "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
Reply | Threaded
Open this post in threaded view
|

Re: [OT] Re: [Newbies] Smalltalk klass dokumentation ?

David T. Lewis
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
Reply | Threaded
Open this post in threaded view
|

Re: [OT] Re: [Newbies] Smalltalk klass dokumentation ?

Randal L. Schwartz
>>>>> "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
Reply | Threaded
Open this post in threaded view
|

Re: Smalltalk klass dokumentation ?

NorbertHartl
In reply to this post by Kommentaren
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" <[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


_______________________________________________
Beginners mailing list
[hidden email]
http://lists.squeakfoundation.org/mailman/listinfo/beginners
Reply | Threaded
Open this post in threaded view
|

Re: Smalltalk klass dokumentation ?

David Mitchell-10
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