Re: [jamboost] new doc stuff

From: Vladimir Prus (ghost_at_[hidden])
Date: 2002-04-09 02:35:55

David Abrahams wrote:

> I really prefer scanning files to extract doc from comments; it could
> solve the function signature problem pointed out above. I'd like to be
> able to write:
>
> # Specifies the documentation for a rule in the current module.
> # If called in the global module, this documents a global rule.
> #
> # <arg>name -- the name of the rule
> # <arg>docs -- The documentation for the rule
> rule document-rule ( name : docs + )
> {
> ...
> }

I prefer it too.

> In summary, the UI design is excellent. 

Agree! This makes the whole system much more easy to use.

> I'd like it a little better if
> the programmer interface were smoother.

After some thinking and then looking at the files attached to
http://groups.yahoo.com/group/jamboost/message/732
I think that find rule docs should be easy. The same about variables. Module 
docs might require some special syntax ("#module" as the first line in 
comment?). Note that doxygen, for example, also require special command to 
mark file docs. And we'll only need a way to shut 
"found such much targets" messages from jam.

If we don't take this route (in general or just not now), I'd appeciate some 
changes to doc formatting. For example, enumerated list in docs for 
regex.split become a straight line in output. I believe it possible to just 
start a new line on elements matching "[-0-9]*)".

- Volodya