Re: [jamboost] Development plan... Doc/Help

From: Rene Rivera (grafik666_at_[hidden])
Date: 2002-04-08 13:39:32

On 2002-04-07 at 11:25 PM, david.abrahams_at_[hidden] (David Abrahams) wrote:

>Firstly, I just want to say that I have a tendency to "make the perfect
>the enemy of the good", as people are fond of saying nowadays, and I've
>been doing that recently with Vladimir and Rene. Now I'm going to try to
>restrain myself. Vladimir has been working on a testing system and Rene
>has been working on a help system for Boost.Build v2. I have been
>encouraging both of them to consider redesigns of what they've already
>done. My bad.

I've learned to deal with that... because I happen to be just like that ;-)

>Rene, I really like what you've done. We need a help system badly. If we
>want to play with other programmer interfaces later I'm sure we will be
>able to convert code to use the new system without too much pain. The
>following points need to be addressed:
>1. How do we document function signatures? Need to deal with
>single-element,+,*, and ? arguments.

I think you're right in that doing file parsing is the way to do that. I was
playing with that yesterday ;-)

>2. There's too much code duplication in print-help-xxx.

In fact most of it was a copy-paste job. I was just trying to get it done
and working. Seeing code duplicated is the best way to figure out what to
factor out. I still haven't done that because I need to consider what
printing html will do to those rules.

>If you /do/ want to play with file parsing, try running "jam -ffoo.jam"
>on the enclosed files. It shows that rule names and argument lists can
>be extracted from Jam files.

I took a quick look. I'll see if I can do more tonight, but I probably won't
get to it until tomorrow. I'd rather get the project/loading stuff working
first.

>However, don't let it distract you if
>either
>a) you don't like the approach, or
>b) it looks like it would take more than a day or so to integrate.
>If you want a builtin rule to read the lines from a file, I could add
>that in an hour.

Right now I prefer the syntax I have (document-*), with the combination of
generating the docs with HDRSCAN and a target. BUt I have a question for
you...

How do you consider the comment "#" style of documentation a better
programmer interface?

-- grafik - Don't Assume Anything
-- rrivera_at_[hidden] - grafik_at_[hidden]
-- 102708583_at_icq - Grafik666_at_AIM - Grafik_at_[hidden]