Re: Something off my chest about Boost

From: pbristow_at_[hidden]
Date: 2019-07-17 11:59:46

> -----Original Message-----
> From: Boost <boost-bounces_at_[hidden]> On Behalf Of Mathias Gaunard
> via Boost
> Sent: 17 July 2019 10:33
> To: boost_at_[hidden]
> Cc: Mathias Gaunard <mathias.gaunard_at_[hidden]>
> Subject: Re: [boost] Something off my chest about Boost
> 
> 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.

I agree with this - but the author needs to do this while writing the code and that slows people down.

However, you are clearly just the man to provide Doxygenation for Spirit!

Paul

PS I am a 'bear of small brain' and I find examples also very helpful. 
Examples of function calls can of course be included in the Doxygen stuff.

Paul A. Bristow
Prizet Farmhouse
Kendal, Cumbria 
LA8 8AB           UK

Go for it.

Paul