[squeak-dev] self error: 'comment only'

Thiede, Christoph Christoph.Thiede at student.hpi.uni-potsdam.de
Sat Mar 21 19:11:08 UTC 2020


> 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.

I think I don't like documentation generation. This is a classical scenario of creating a representation that lacks liveness and needs to be kept in sync, making it impossible to edit the generated document, unless the synchronization is implemented as a bidirectional process. Especially in Squeak, we should be very careful to create such derived representations. Ideally, we should also never copy documentation stuff into the Swiki, but implement a hook/special syntax there that allows citing it directly from the Swiki server's image.

Best,
Christoph

________________________________
Von: Squeak-dev <squeak-dev-bounces at lists.squeakfoundation.org> im Auftrag von David T. Lewis <lewis at mail.msen.com>
Gesendet: Samstag, 21. März 2020 20:03:36
An: The general-purpose Squeak developers list
Betreff: Re: [squeak-dev] self error: 'comment only'

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.

Dave


> 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
> --
> tim Rowledge; tim at rowledge.org; http://www.rowledge.org/tim
> <-------- The information went data way -------->
>
>
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.squeakfoundation.org/pipermail/squeak-dev/attachments/20200321/90f9c406/attachment.html>


More information about the Squeak-dev mailing list