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

tim Rowledge tim at rowledge.org
Fri Jun 13 16:50:16 UTC 2014


On 13-06-2014, at 9:37 AM, Eliot Miranda <eliot.miranda at gmail.com> wrote:

> 
> So do I.  Personally I like class comments.  I don't want to look for methods that contain help text. 

Me too.

There’s nothing to prevent an extension of the HelpBrowser to have it use the contents of class comments and/or other sources of text, which would make it really easy for people to add content. 

We probably don’t want to clutter the image with large strings (there’s already too many) and class comments get stored in the changes which is a sensible place to have them. It shouldn’t be difficult to make any other local documentation live in the same place(s) - we only need a convention on the method name(s) to allow specified method comments to be sucked in. When online it shouldn’t be beyond us to suck in swiki page content.

But the mechanism isn’t anywhere near as important as the content. Lots of us are capable of the programming for the mechanism but fewer have the writing talent to produce good documentation - let alone the time.



tim
--
tim Rowledge; tim at rowledge.org; http://www.rowledge.org/tim
The Static Typing Philosophy: Make it fast. Make it right. Make it run.




More information about the Vm-dev mailing list