Re: [jamboost] Bugs/Moratorium

From: Rene Rivera (grafik666_at_[hidden])
Date: 2002-03-26 22:34:00

[and finally back from an ATT network outage...]

On 2002-03-26 at 07:33 PM, david.abrahams_at_[hidden] (David Abrahams) wrote:
>----- Original Message -----
>From: "Rene Rivera" <grafik666_at_[hidden]>
>> - We describe what features and, briefly, properties are. But we don't
>> describe what they all are and what effect they have. The only thing
>we do is
>> point to the features.jam, which is in no way documented.
>
>True. That's a bigger problem, too. How will features get added to the
>system? They may creep in from various toolset/platform/library support
>files. In a modular system, how do you document those components?

Other than discipline there is no easy answer :-( But the most helpful
documentation I write is the one I write next to the code. Having done
javadocs, and doing doxygen, doing documentation for modules where the modules
are and having such a tool extract them into a cohesive document works. Not as
effectively as a prose description and example but better than nothing.

>> are GCC*, STLPORT*, and PYTHON*.
>
>I completely agree; however, we could spend weeks documenting all this
>stuff which is going to be thrown out (soon, I hope!)

My point was that we have functionality that may of us don't know about. And
we could at least document some of it so that we don't conveniently forget to
implement it in V2.

>> >From both a user and developer viewpoint what I'd like to see is
>documentation
>> divided into three audiences: users, programmers, developers.
>>
>> Users are those writing their own Jamfiles, and nothing else. This
>group needs
>> a good description of all the possible constructs the can make use of
>and how
>------------------------^^^^^^^^^^^^^^^^^^^^^^^^^^^
>> the work from a production aspect. I consider this the cause and
>effect
>> viewpoint, they have an intended effect and want to know the cause so
>they can
>> make use of it.
>
>I think that's a tall order. As you know, the constructs are limitless,
>because users can start programming. What we /can/ do for users is show
>them the basic usage, and tell them that supplied modules (e.g. for
>STLPort support) will add their own capabilities. It would be worth
>having a way to get help from the command-line:
>
> bjam --help-stlport
>
>to dump information about how to use the stlport module.

Possible constructs was a bad way of putting it, sorry. What you describe is
really what I meant. After all we can document a combinatorial set of
functionality ;-\

I'm all for having the system include "online" help, hooray :-) And my
previous mention of in-code documentation seems like something we can do to
provide that. A model we can look at is the Perl doc system. It has the same
problems as we have, incremental, and highly modular code. And it manages to
provide documentation for all of it.

So maybe a few rules that provide documentation in the form of long, short,
and brief. We can tie this either to modules or rule, or both. And then it
becomes possible to provide the "bjam --help-<module/rule-name>"
functionality.

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