On Thursday, October 10, 2013 10:29:20 PM Mathias Gaunard wrote:
On 10/10/13 21:00, Andrew Hundt wrote:
http://www.boost.org/doc/libs/1_54_0/doc/html/boost_container_header_refer ence.html#header.boost.container.static_vector_hpp
This second link is the typical header documentation throughout boost. When I first started using boost it was months before I realized that in these header synopsis I could click on the words of the class to see the full documentation of that class, in this case "static_vector". Much of the time I just felt confused and lost. I think this is indicative of a layout and user interface that needs some improvement.
Documentation like this is generated by preprocessing Doxygen XML output to integrate it into Boostbook and have a good look for C++ references. It has most of what you can expect from Doxygen + the Boostbook stuff which gives better cross-referencing than simple Doxygen.
I personally don't understand how one cannot notice that the blue bits that become underlined when you hover them and change colors once visited are hyperlinks (especially since that's also true for any other hyperlink in Boost docs and most of the World Wide Web).
I have had the same experience as Andrew. I only figured out that those are links when I started working on my own library docs and I _knew_ there had to be more information. Now surely this is embarassing from my perspective now, but somehow the header file doc was just a bunch of source-code to me that was impossible to read and handle.
What do you suggest would be better?
Maybe it would be more readable if we didnt use a header-file based organization for the reference, but rather compile lists of classes and functions for a library. The reference for individual classes/docs are quite good then - once you found them. Best, Mario