[squeak-dev] self error: 'comment only'
David T. Lewis
lewis at mail.msen.com
Sat Mar 21 19:03:36 UTC 2020
On Sat, Mar 21, 2020 at 11:21:39AM -0700, tim Rowledge wrote:
> > On 2020-03-17, at 12:56 AM, K K Subbu <kksubbu.ml at gmail.com> wrote:
> > It already does - Browser -> Object -> show all comments -> class side
> Hunh. Never noticed that before; which is an example of a mix of "long-habit making new stuff almost invisible" and "too long menu disease".
I overlooked this too. Thanks Subbu!
> I think it does the wrong thing though; a more consistent approach would be to have the HelpBrowser page with that info installed in the HB that opens when you ask for Help. Removes a then-pointless menu entry and make the HB more useful.
> A related issue is the lack of actually useful class comments - and indeed the fact that class comments are a small part of the total need to explanations. If we were to make really thorough use of the HB to document things one might argue that individual class comments would become irrelevant. Certainly the tragically simplistic approach I've seen (I think it was called javadoc?) that simply gathers up every comment and tries to pretend that it makes actual documentation is not one to copy.
Actually, javadoc can do a very nice job of generating documentation
if someone has taken the time to write good comments in the first
place. Not unlike the situation in Squeak.
> Making good doc and good tools to make that easily available and easy to keep up to date is hard work. I think we have a lot of decent starting points though. We can, for example fetch swiki pages fairly easily, which would be a great thing to improve for major doc items. They can be updated easily by a wide community, which is hopeful. A downside is the requirement to be online, which means we might want to work out a way of having some basic doc held in local space (probably best is the sources file since we usually at least have that) as well. And being better at parsing the content of swiki pages would be nice; or perhaps extending the swiki system to be able to return data in a more digestible form when the requestor is an HB?
> tim Rowledge; tim at rowledge.org; http://www.rowledge.org/tim
> <-------- The information went data way -------->
More information about the Squeak-dev