Re: [jamboost] doc module!

From: David Abrahams (david.abrahams_at_[hidden])
Date: 2002-07-08 10:45:47

From: "Rene Rivera" <grafik666_at_[hidden]>

> [2002-07-08] David Abrahams wrote:
>
> >Rene, I've just been playing around with your new help system, and I
have
> >to say this is *totally* cool!
>
> Thanks :-)
>
> >Obviously, some refinements are needed, e.g. in output formatting and in
> >speed for --help-all. Anyway, I find it very exciting!
>
> Formatting is on my list, output to HTML, handling "module _X_ { }"
syntax,
> variable parsing is a bit strange, and not being able to get the docs for
> "os.path" because of the "." :-(

I will fix up the way feature.jam works so that the docs don't all come out
in feature-space. Here are some formatting things I'd like to see:

* Don't document class methods at the outer level, but only when help on
the class is requested.

* Instead of "Call as ( ... )", just put the argument list next to the
function name. See python's help(func) for an example:

>>> help(atexit.register)
Help on function register in module atexit:

register(func, *targs, **kargs)
register a function to be executed upon normal program termination

func - function to be called at exit
targs - optional arguments to pass to func
kargs - optional keyword arguments to pass to func

* Dash (or colon) makes a better separator than semicolon for
argument-name -> description

* Preserve paragraph breaks in comments

* Preserve line breaks in comments (really!) or provide auto-detection of
line breaks in numbered lists, etc. Not sure why we would have to add line
breaks unless someone was doing obscene things with his code.

> As for the speed of help-all... It might take special parse handling for
> that because it has to parse all the available files and it's not exactly
> fast in doing that. I'm thinking of a short version of the parse is in
order
> for that.

Try -d+10 to get profiling information.

-Dave