<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="Generator" content="Microsoft Exchange Server">
<!-- converted from text --><style><!-- .EmailQuote { margin-left: 1pt; padding-left: 4pt; border-left: #800000 2px solid; } --></style>
</head>
<body>
<meta content="text/html; charset=UTF-8">
<style type="text/css" style="">
<!--
p
{margin-top:0;
margin-bottom:0}
-->
</style>
<div dir="ltr">
<div id="x_divtagdefaultwrapper" dir="ltr" style="font-size:12pt; color:#000000; font-family:Calibri,Helvetica,sans-serif">
<p>> <span style="font-size:12pt">Actually, javadoc can do a very nice job of generating documentation </span><span style="font-size:12pt">if someone has taken the time to write good comments in the first </span><span style="font-size:12pt">place. Not unlike
the situation in Squeak.</span></p>
<div><br>
</div>
<div>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.</div>
<div><br>
</div>
<div>Best,</div>
<div>Christoph</div>
<p></p>
<div id="x_Signature">
<div id="x_divtagdefaultwrapper" dir="ltr" style="font-size:12pt; color:rgb(0,0,0); font-family:Calibri,Helvetica,sans-serif,EmojiFont,"Apple Color Emoji","Segoe UI Emoji",NotoColorEmoji,"Segoe UI Symbol","Android Emoji",EmojiSymbols">
<div name="x_divtagdefaultwrapper" style="font-family:Calibri,Arial,Helvetica,sans-serif; font-size:; margin:0">
<div><font size="2" color="#808080"></font></div>
</div>
</div>
</div>
</div>
<hr tabindex="-1" style="display:inline-block; width:98%">
<div id="x_divRplyFwdMsg" dir="ltr"><font face="Calibri, sans-serif" color="#000000" style="font-size:11pt"><b>Von:</b> Squeak-dev <squeak-dev-bounces@lists.squeakfoundation.org> im Auftrag von David T. Lewis <lewis@mail.msen.com><br>
<b>Gesendet:</b> Samstag, 21. März 2020 20:03:36<br>
<b>An:</b> The general-purpose Squeak developers list<br>
<b>Betreff:</b> Re: [squeak-dev] self error: 'comment only'</font>
<div> </div>
</div>
</div>
<font size="2"><span style="font-size:10pt;">
<div class="PlainText">On Sat, Mar 21, 2020 at 11:21:39AM -0700, tim Rowledge wrote:<br>
> <br>
> <br>
> > On 2020-03-17, at 12:56 AM, K K Subbu <kksubbu.ml@gmail.com> wrote:<br>
> > <br>
> >> <br>
> > <br>
> > It already does - Browser -> Object -> show all comments -> class side<br>
> <br>
> 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".<br>
> <br>
<br>
I overlooked this too. Thanks Subbu!<br>
<br>
<br>
> 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.<br>
> <br>
> 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.<br>
> <br>
<br>
Actually, javadoc can do a very nice job of generating documentation<br>
if someone has taken the time to write good comments in the first<br>
place. Not unlike the situation in Squeak.<br>
<br>
Dave<br>
<br>
<br>
> 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?
<br>
> <br>
> tim<br>
> --<br>
> tim Rowledge; tim@rowledge.org; <a href="http://www.rowledge.org/tim">http://www.rowledge.org/tim</a><br>
> <-------- The information went data way --------><br>
> <br>
> <br>
> <br>
<br>
</div>
</span></font>
</body>
</html>