Re: [jamboost] Bugs/Moratorium

From: Rene Rivera (grafik666_at_[hidden])
Date: 2002-03-25 02:17:48

On 2002-03-24 at 04:13 PM, david.abrahams_at_[hidden] (David Abrahams) wrote:

>
>----- Original Message -----
>From: "Rene Rivera" <grafik666_at_[hidden]>
>
>Tests are almost more important than docs.

Yes, and no. It's hard to test undocumented functionality.

>Vladimir wrote a snazzy
>python testing system but I never got around to trying to use it. We'd
>need a dummy toolset definition for testing purposes. All it would have
>to do is echo or cat some simple data into files.

Great! Is that the *.py files in tools/build/test? And I'd be willing to add
some of the test cases I've had to write when encountering bugs.

>> We have docs on the internal implementation of V2 will be but not of
>what the
>> top level features it's trying to implement, other than the existing
>V1 code.
>
>Partly that's because we really have a code /framework/, with both
>programmer-level and user-level functionality, and there's a continuum
>between users and programmers of this system. That can make it difficult
>to decide which elements to expose in the top-level docs.

Yes, and that accounted for a large part of my original confusion as a user
when I first encountered Boost.Build.

>What do you think needs to be covered in the top-level docs which
>currently isn't?

What I'd like to see is a better division between documentation for users of
Boost.Build, and the rest of the documentation.

Since I was looking at the docs tonight here are some things that I saw...

- Even though we document description of main targets, we don't really
document the various main targets that are possible.One description for all of
them doesn't cut it from a users point of view.

- There are a few non main targets we don't describe. "unit-test" is one, and
is one that I was unaware of for some time. That's the most glaring and there
are probably others I don't know.

- All the python targets, pyd, testing, etc. aren't documented, as far as I
can tell.

- 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.

- This applies only to V1, but we certainly lack in describing even the
minimal set of variables we have to set in order to get Boost to build. And
therefore aren't even close to documenting what all the various variables one
can set to change the behavior of things. Ones that immediately come to mind
are GCC*, STLPORT*, and PYTHON*.

>>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.

Programmers are users that are supporting either an extended Boost.Build
system or a custom one using Boost.Jam. They want to know some of the
internals of the system, but usually just enough to get their stuff working.
For example they would not be interested in the v2 architecture doc, but would
be interested in the "Internals" doc section we currently have.

Developers, that's us, are the ones doing the base coding. We need to know
everything, but we also don't need info to be totally digested to make use of
it. Also in this group would be anyone providing patches to new features
they've implemented.

I know that's a lot, and that few of us like writing documentation but we have
to do it eventually. I'm not suggesting we do this now, that would be just
very bad, but thinking about it at minimum. And at best coming up with a
structure for the documentation would be good.

And lastly, I think testing and docs are parallel tasks. If we are testing
something we should be documenting that something.

OK, that's enough rambling for tonight, sleep beckons.

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