Re: [boost] Something off my chest about Boost

-----Original Message----- From: Boost On Behalf Of Mathias Gaunard via Boost Sent: 17 July 2019 10:33 To: boost@lists.boost.org Cc: Mathias Gaunard Subject: Re: [boost] Something off my chest about Boost

On Tue, 16 Jul 2019 at 21:09, Maarten Verhage via Boost 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