On 17 Dec 2004, at 22:05, Tom Gersic wrote:
This comment illustrates exactly the problem with the bulk of the documentation. Our tendency is to document classes, not usage patterns. This makes the documentation useful for people who already know what they're doing, but not so helpful for people who don't.Agreed. I also think there's a need for more code-syntax documentation. Since the SC3 syntax is somewhat different from other programming languages with which I'm familiar (I've never coded in Smalltalk before, so maybe that's my problem...I'm more of a Perl/PHP programmer by trade), sometimes simple constructs are difficult to figure out how to code. Figuring out simple coding-issues takes away time from working on more important things. This list has been extraordinarily helpful, but there are some things that should be documented, such as how to implement a hash, or how to write a switch statement...both are things I know how to do in SC now, but I had some trouble figuring out initially. Oh, and string manipulation...I think that's another area that I had some difficulty with.
Switch is documented, in the Control-Structures helpfile, and for that matter in the Object helpfile as well. Both have examples.
String has a pretty complete helpfile too, although it does of course inherit a lot of methods. That is a problem in OO languages though, as documenting all inherited methods would make the doc incredibly bloated.
S.