On 9/7/2017 10:21 PM, Florian Lindner via Boost wrote:
Hello,
I really love to use boost libraries in my project, but I always wonder, for such an accomplished project, why is the documentation so bad?
A few examples:
I want to get familiar with http://www.boost.org/doc/libs/1_65_1/libs/ptr_container/. What do I need to include? Neiter the tutorial, the reference or the usage guidelines mention a #include line. This is something which stroke me quite often at various boost libs.
Also with the ptr_container lib, I want to find the refrence for the ptr_vector::insert function. I got to scan the reference pages of all members of it's class hierarchy to find the insert() function (it's in ptr_sequence_adapter).
References and example code often have no syntax highlightning and no linking and it's extremely hard to find documentation for a specific symbol, or from there, to jump to the source code.
I would really like to have a more uniform and a documentation that not feels like a annotated source code dump.
I use doxygen for my own projects and I know it can generate nicely looking, with syntax highlightning and linked documentation.
Please, don't take this offensive, it's just some feedback I wanted to give a long time.
Feel free to open an issue for any library's documentation you feel inadequate. I completely agree with you that every library needs to specify these 3 things near the beginning of the docs: 1) Level of c++ supported if it is anything above c++03. 2) Header files needed 3) Namespaces used with optionally: 4) Build instructions for non header-only libraries Furthermore I believe that some Boost documentation suffers from the syndrome that library authors believe that adequate docs mean examples/tutorial + reference, without having to provide any general explanation and discussion of the actual concepts of the library. But obviously most Boost libraries are first rate in explaining themselves and it is very hard to change the mindset of those few library authors who do not want to explain their libraries in a more expansive manner.
Best, Florian