Re: Something off my chest about Boost

From: Mathias Gaunard (mathias.gaunard_at_[hidden])
Date: 2019-07-17 09:33:10

On Tue, 16 Jul 2019 at 21:09, Maarten Verhage via Boost
<boost_at_[hidden]> wrote:

> Speaking for myself. I think the first bits to get started with a library are on a sufficient level. You know the tutorial and the example code. But I get lost when I want to use the library for my own application domain. Then I do need library facilities not covered in the example code and sometimes the documentation mentions only the syntax. As I would imagine the library author working on his/her library judging whether to add a facility or not. Finally decided to add something: *the thought/motivation that goes along with that*, that would be so valuable for me to read that in the documentation!! Yes, I’m annoyed that I cannot read that in the documentation.
>
> Another issue is when example code introduces three or more facilities at once. Then it is very hard for me to see how these bits relate to each other to make it useful for myself.

Personally I rarely even read textual documentation (examples,
tutorials...), it is usually more useful to just look at the reference
or the code itself (which should embed documentation in the form of
comments for the parts that matter).
Textual documentation is often glossing over some details which only
make sense if you already are familiar with how the library is
organized or showing trivial things that have little value.

> 2) Specifically for Spirit X3, a part on Parser Directives: https://www.boost.org/doc/libs/develop/libs/spirit/doc/x3/html/spirit_x3/quick_reference/directive.html
> I would very much like that the reason why each directive is added along with a minimal example that shows how to use just that directive.

The main problem with the Spirit documentation is that it has
tutorials and a reference of the different parser operators, but there
is no real reference documentation of the functions and other software
infrastructure that actually drive the work and the requirements their
inputs must satisfy. So you have to infer that from tutorials or just
look at the source code.
This is a common problem with a lot of Boost libraries.

Anyway, for your problem, your confusion might come from the fact that
you don't realize that parsing with Spirit combines an attribute
parser and a skip parser, that the skip parser is called before and
after each call to the attribute parser, and that parsing yields the
attribute. Those directives you linked to simply allow you to change
how those are called or what result they yield within a localized
context.
There indeed doesn't appear to be any documentation on this.

Now a simple idea one might implement to improve the quality of boost
documentation is simply mandate reference documentation in the form of
a list of public header files with the public functions they declare
together with their signature.
That sort of thing is easily generated by Doxygen and it is already
well integrated into the Boostbook toolchain.