Re: [jamboost] new doc stuff

From: David Abrahams (david.abrahams_at_[hidden])
Date: 2002-04-06 19:36:06

----- Original Message -----
From: "Rene Rivera" <grafik666_at_[hidden]>

> On 2002-04-06 at 05:17 PM, david.abrahams_at_[hidden] (David Abrahams)
wrote:
>
> >
> >> You can try creating a fake build directory somplace else if you
wan't
> >to
> >> get it to work. Or wait till I fix it.
> >
> >You fix. I test.
>
> OK, fixed. Try it now.

OK, I rolled in the Perforce stuff and updated all of our .jam files so
that things work again. Now, testing --help:

bjam -sJAMFILE=test.jam --help-modules
Modules:

These are all the known modules. Use --help-<module> to get more
detailed
information.

doc isn't listed here, not to mention other stuff.

cd c:/boost/tools/build/new/
bjam -sJAMFILE=test.jam --help-rules
For more information consult the documentation at
'http://www.boost.org'.

Shouldn't there be some rule docs, or do we mean to document only
"exported" rules here?

suppose I have a rule:

rule foo ( bar baz + : mumble blocks ? : g * )

How do I document the arguments and the function signature?

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 + )
{
...
}

Do you know about 'local rule foo ( ... )' syntax? It seems like a bunch
of rules in doc could be local.

In summary, the UI design is excellent. I'd like it a little better if
the programmer interface were smoother.

-Dave