[Vm-dev] Proposing class Category README or HOWTO for easy access to documentation within the system

Eliot Miranda eliot.miranda at gmail.com
Fri Jun 13 16:37:35 UTC 2014


On Thu, Jun 12, 2014 at 11:29 AM, gettimothy <gettimothy at zoho.com> wrote:

>
> Hi All,
>
> Stefan Ducasse replied to me regarding my synapsis of the CMakeVMaker code.
>
>
>  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
> add the comment to a class so that it is not lost.* Information external
> to classes is often lost.*
>
>
> And I agree with him.
>

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.

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.


>
> 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.
>
> 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.
>
> 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.
>
>
> just my .02
>
> cheers.
>
> tty
>
-- 
best,
Eliot
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.squeakfoundation.org/pipermail/vm-dev/attachments/20140613/32d904a1/attachment.htm


More information about the Vm-dev mailing list