Re: [jamboost] new doc stuff

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

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 find it better as well.

> In summary, the UI design is excellent. 

Agree! This is crucial in making boost.build usable.

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

After some thinking and then looking at files attached to
http://groups.yahoo.com/group/jamboost/message/732
I think that scanning jamfile for rule docs is not so hard. Guess variable 
docs are easy too. Module docs might require some tricks (eg, staring
the first comment line with "#module"). For example, doxygen also require 
special command to mark file docs. And we'll need a way to shut up 
"found such many targets" message from jam.

If we don't go this route, I'd appreciate some changes for formatting the 
docs. For example, look at the docs for regex.split. When I converted them to 
use the doc module, the numbered list just became straight line. A simple 
solution would be to start new line on everything that matches
"[-0-9]*)". 

- Volodya