Bram Neijt wrote: > I can see why an online documentation system doesn't seem needed. And > the short awnser is: it isn't. Smalltalk was designed to be used while > working in the system, like Squeak (as far as I can see). So all > documentation can be done with a browser/viewer within the virtual > machine.
On the contrary: when I first started learning (GNU) Smalltalk, I referred to the generated HTML docs extensively. In addition, having to install a package in order to find out anything about it is something I find very off-putting about other-dialect packages. I'm sure that the same is true of GSt. > Common documentation systems include things like: examples, verbose > argument explanaition, return value and type explenation, possibly > TODO's, a 'see also' list, links, class variable documentation, etc. > > So to awnser the question 'what, if anything, would a markup add?': > one or more of the above (as needs be ;-) ). (Keep in mind that this > didn't start because of a lack of documetation or it's quality: simply > because I would like a wiki system with that same markup.) It seems to me that all of the additional information that is worth having is either a link or a link in disguise. [chopping up the replies - I hope this doesn't offend anybody] > The Javadoc/doxygen method is: > PositionableStream >> copyFrom: start to: end > "Answer the collection on which the receiver is streaming, from > the start-th item to the end-th > @arg start The starting position > @arg end The ending position > @see Smalltalk.Collection > " > ^collection copyFrom: start to: end OK, but the method is now five lines of comment and one of code, and arguably didn't need the two lines of comment that it started with. What I was getting that was that, if you have "copyFrom: start to: end", and you also have "from the start-th item to the end-th", what additional information are you getting from "@arg start The starting position" and "@arg end The ending position" ? Also, if "Answer the collection" was written "Answer the Collection", then Collection could be made into a link without adding any markup. Mike _______________________________________________ help-smalltalk mailing list [email protected] http://lists.gnu.org/mailman/listinfo/help-smalltalk
