[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Help-smalltalk] Documentation syntax
From: |
Mike Anderson |
Subject: |
Re: [Help-smalltalk] Documentation syntax |
Date: |
Thu, 17 Aug 2006 00:46:28 +0000 |
User-agent: |
Mozilla Thunderbird 1.0.5 (X11/20050711) |
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] Documentation syntax, Bram Neijt, 2006/08/15
- Re: [Help-smalltalk] Documentation syntax, Mike Anderson, 2006/08/16
- Re: [Help-smalltalk] Documentation syntax, Paolo Bonzini, 2006/08/16
- Re: [Help-smalltalk] Documentation syntax, Bram Neijt, 2006/08/16
- Re: [Help-smalltalk] Documentation syntax, Brian Brown, 2006/08/16
- Re: [Help-smalltalk] Documentation syntax,
Mike Anderson <=
- Re: [Help-smalltalk] Documentation syntax, Paolo Bonzini, 2006/08/17
- Re: [Help-smalltalk] Documentation syntax, Stewart Stremler, 2006/08/17
- Re: [Help-smalltalk] Documentation syntax, Bram Neijt, 2006/08/19
- Re: [Help-smalltalk] Documentation syntax, Mike Anderson, 2006/08/19
- Re: [Help-smalltalk] Documentation syntax, Mike Anderson, 2006/08/19