<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Thu, Jun 12, 2014 at 11:29 AM, gettimothy <span dir="ltr"><<a href="mailto:gettimothy@zoho.com" target="_blank">gettimothy@zoho.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"> <br><u></u><div><div style="font-size:10pt;font-family:Verdana,Arial,Helvetica,sans-serif"><div>Hi All,<br></div><div>
<br></div><div>Stefan Ducasse replied to me regarding my synapsis of the CMakeVMaker code.</div><div><br></div><div><br><blockquote style="border-top-color:rgb(204,204,204);border-left-color:rgb(204,204,204);border-right-color:rgb(204,204,204);border-bottom-color:rgb(204,204,204);border-top-width:1px;border-left-width:1px;border-right-width:1px;border-bottom-width:1px;border-top-style:solid;border-left-style:solid;border-right-style:solid;border-bottom-style:solid;padding-top:7px;padding-right:7px;padding-bottom:7px;padding-left:7px;background-color:rgb(245,245,245)">
<div> Igor created all the logic of the CMakeGenerator but I guess that he did not add good class comments so I thought that it would be great if you can<br>add the comment to a class so that it is not lost.<strong> Information external to classes is often lost.</strong></div>
</blockquote></div><div><br></div><div>And I agree with him.</div></div></div></blockquote><div><br></div><div>So do I. Personally I like class comments. I don't want to look for methods that contain help text. The convention there is to provide an "examples" category containing example methods. So please let's /not/ add another category or convention for including documentation in methods, categories or classes. There are also tests. But as for externally readable help or more general browsable help I agree, Wikis and the Help system are good places. The most important thing is knowing where these are, so putting options on the screen menu or the menu bar is really really important.</div>
<div><br></div><div>However, copying Pharo mad making the lack of a class comment in the browser noticeable (colouring the " ? " button red when there's no class comment for example) is a really good idea.</div>
<div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div><div style="font-size:10pt;font-family:Verdana,Arial,Helvetica,sans-serif"><div> </div><div><br></div>
<div>In Linux/Open Source world, are the conventions of README and HOWTO. I propose that Squeak adopt two class categories for developers to add easy access to documentation on subsystems in the README category and quick howto_foo_a_bar classes in the HOWTO category.<br>
</div><div><br></div><div>I know we have the web, and there is a Help system, but I find the Help system a bit clunky to use and breaking from Squeak environment to Web for information breaks the flow.</div><div><br></div>
<div>A recent example of where this proposal would come in handy is the recent discussion about reviving Tweak for Squeak 4.5/4.6. The time investment to get up to speed is vastly increased by having to hunt for information.</div>
<div><br></div><div><br></div><div>just my .02</div><div><br></div><div>cheers.</div><div><br></div><div>tty</div></div></div></blockquote></div>-- <br>best,<div>Eliot</div>
</div></div>