Might I suggest a close look at Donald E. Knuth's Literate Programming, and WEB, CWEB, etc.

Donald E. Knuth's home page:
<http://www-cs-faculty.stanford.edu/~uno/index.html>

The CWEB System of Structured Documentation
<http://www-cs-faculty.stanford.edu/~uno/cweb.html>

Daniel Mall's website for Literate Programming
<http://www.literateprogramming.com/>

Ken G. Brown

At 5:18 PM -0800 2/23/10, Andreas Raab apparently wrote:
>Hi -
>
>I'd like to add a feature request to HelpSystem: Adding a very simple pattern that can be used to provide structure in class comments, perhaps along the lines of Wiki syntax. Why would that be good? Several reasons:
>
>a) Currently a book depends on the presence of HelpSystem (i.e., via subclassing). This needs to be fixed - we need to be able to have documentation in the system without necessarily requiring a viewer.
>
>b) Typing in '' quotes is pretty insane when you quote text. The constant use of it''s instead of it's etc. is VERY distracting. Code examples look like crap etc. In the class comment you can write straight away.
>
>c) Class comments are WYSIWIG for the purposes of HelpSystem. One can create links, doIts, highlights and see the effects right away. This isn't easily possible otherwise since we don't have literal text syntax.
>
>d) It's the right place for documentation anyway.
>
>I'm not saying that comments are the only way by which HelpBooks should be created but I think that this should be one of the ways that HelpSystem directly supports. In fact what happened was that I was trying to use HelpSystem and ended up to move all the docs into the class comment for all of the above reasons.
>
>
>For example, we could just say that we define a help book marker and a topic boundary and then your class comment looks like here:
>
>This is a sample class comment.
>
>[HelpBook: 'MyClass Introduction']
>
>Anything you see here will be displayed as the abstract for the help book.
>
>=== MyClass Introduction
>
>This is an introduction to MyClass. You can read about its most interesting feature.
>
>=== MyClass Frobnification
>
>Frobnification, the process of frobnifiying a snuzzle, is the main purpose of MyClass.
>
>[HelpBook: 'MyClass Reference']
>
>=== frobnify: aSnuzzle
>
>This is the main interface to MyClass. It takes a Snuzzle and frobnifies it. Note that there is some discussion about whether the result is a fronbnified or a frobnificated snuzzle.
>
>Example:
>
>	MyClass new frobnify: RectangularSnuzzle new.
>
>
>Etc. The point being that it's easy to edit, you get both a class comment and a book out of it, and people looking at it will say "holy cow! i guess there *is* some documentation somewhere here :-)"
>
>I'd be happy to help you with this if you think it's worthwhile.
>
>Cheers,
>  - Andreas