C++: Boost Libraries, Code Documentation & Examples

I have a loving relationship with the Boost C++ libraries, but I have a real hate of their documentation, not just it's style, but the mistakes and fragmentation they build into it.

When I search for say "socket", I want it to take me to boost::asio::tcp::ip::socket.  But instead it takes me on a run around, and when I finally get to boost::asio::tcp::ip::socket the examples and namespace being used is incomplete, it assumes a bunch of things, and you get told to look in tcp::ip::socket.

This is fine, if your reader knows to assume boost::asio as well, but if you're new to the whole boost project, you don't know sockets live in asio, you might be looking for boost::net, or boost::networking, or boost::network or just boost::tcp.  And you're stuck, lost, you have to leave the boost documentation search and go to google.

To fundamentally have to leave the documentation of an actual project website, and use a third party in this way is fundamentally telling you your documentation is flawed.

Then, there are mistakes in the documentation, this is annoying, but when the mistakes are in the examples given it's unforgivable, you're basically giving your users the finger, because not only are you teasing them with an example, but when it doesn't work they are again cast out into the wilds of the internet.

Case in point, again the socket, it's example code shows it as "soocket".  A typo yes, but it tells me two things, first of all, the code was not proof read, and second; and perhaps most importantly; the examples are not from working code, they've never been run, because it's not soocket, and the compiler would instantly tell anyone trying to run that code soocket is invalid.  Examples SHOULD ALWAYS BE LIFTED FROM A WORKING EXAMPLE!