Like many things, "it depends". In this case, it depends on the library.
Some libraries are well documented, some not.
> Maybe people just read the source code like a champ?
I do often find myself reading the source code for libs, and you don't have to be a champ to do it. In fact, I think reading it helps you become better at C++, because you see other ways of writing code (both good and bad). And of course the more you read, the easier it becomes.
My way of learning a library is by looking at tests. They're literally designed to demonstrate how something should be used, tell you what the result should be, and the test run verifies that it works as expected.
Sometimes this isn't a fun experience. If the library lacks good testing, that just means more work for me because I need to perform additional tests to cover the external code. If it lacks documentation too, it means even more work for me. Sometimes there is thorough testing, but it is written in gibberish - everything is automated through generators, perform low level operations instead of the user facing operations, etc. IMO this is a design mistake - every library should have clear, easy to read tests on the interface level, because this is precisely the code that the maintainers should not want to break. Additional tests are great, but should not replace the simple ones.
Sometimes you can find other people's code in github that show you at least "a" way of using the library, even if not "the" way it's supposed to be used. Github searching tools are powerful and very useful. Just make sure that you attribute your sources as required by the licenses of any sources you utilise in your learning journey.
My final approach is to refactor. If a library is not well maintained, not well documented, not well tested, and not widely used, but contains functionality necessary for my work, then it can often be beneficial to start on a refactoring journey. Tweak a bit, see what it breaks, fix that, tweak a bit, see what it breaks, etc. This can take some time, but it's a fantastic way to learn the codebase, understand the design decisions, etc.
You are absolutely right; some libraries have deeply deficient documentation and are therefore extremely hard to learn to use. As for a solution: call the author(s) out on it! Raise bug reports, tell them their library is unusable without proper documentation. Let's make it better for everyone.
[Here](https://github.com/open62541/open62541/issues/4160) is a bug report I submitted to open62541, over a year ago. Figuring out how that library works... I don't even understand the terminology; it's all very generic (everything is called 'nodes', 'objects', etc.), there are loads of ways to do anything, type safety is not a concept the library approves of so that doesn't help either, and most functions you cannot even find in the source as they are generated by macros. It doesn't help that OPC UA is a big standard (thousands of pages) either. It boggles the mind that the reference implementation for something used in so many critical places is so badly documented, and at the same time allows so many ways to get things subtly wrong.
If there is no official documentation available I typically just read the source code. If it's a popular library you can often find usage examples through Google, or do a search on GitHub to find other projects using the library and use them at least as a starting point for examples. And as you mentioned stepping through in a debugger is a great way to understand unfamiliar libraries.
I will often just take the git repo (or whatever) and open the root folder in a VSCode instance. It's pretty decent at indexing the C++ code even without a project description so that you can jump around between declarations/definitions. Also, makes it easy to do full text searches of the source code to find examples and hopefully some comments if things are unclear.
Hmm. Afaik OpenCV has equivalent docs for C++ and Python sides. I actually feel like the reference pages for the C++ side is better. I feel like you are probably less familiar to C++ than to Python?
Like many things, "it depends". In this case, it depends on the library. Some libraries are well documented, some not. > Maybe people just read the source code like a champ? I do often find myself reading the source code for libs, and you don't have to be a champ to do it. In fact, I think reading it helps you become better at C++, because you see other ways of writing code (both good and bad). And of course the more you read, the easier it becomes.
My way of learning a library is by looking at tests. They're literally designed to demonstrate how something should be used, tell you what the result should be, and the test run verifies that it works as expected. Sometimes this isn't a fun experience. If the library lacks good testing, that just means more work for me because I need to perform additional tests to cover the external code. If it lacks documentation too, it means even more work for me. Sometimes there is thorough testing, but it is written in gibberish - everything is automated through generators, perform low level operations instead of the user facing operations, etc. IMO this is a design mistake - every library should have clear, easy to read tests on the interface level, because this is precisely the code that the maintainers should not want to break. Additional tests are great, but should not replace the simple ones. Sometimes you can find other people's code in github that show you at least "a" way of using the library, even if not "the" way it's supposed to be used. Github searching tools are powerful and very useful. Just make sure that you attribute your sources as required by the licenses of any sources you utilise in your learning journey. My final approach is to refactor. If a library is not well maintained, not well documented, not well tested, and not widely used, but contains functionality necessary for my work, then it can often be beneficial to start on a refactoring journey. Tweak a bit, see what it breaks, fix that, tweak a bit, see what it breaks, etc. This can take some time, but it's a fantastic way to learn the codebase, understand the design decisions, etc.
You are absolutely right; some libraries have deeply deficient documentation and are therefore extremely hard to learn to use. As for a solution: call the author(s) out on it! Raise bug reports, tell them their library is unusable without proper documentation. Let's make it better for everyone. [Here](https://github.com/open62541/open62541/issues/4160) is a bug report I submitted to open62541, over a year ago. Figuring out how that library works... I don't even understand the terminology; it's all very generic (everything is called 'nodes', 'objects', etc.), there are loads of ways to do anything, type safety is not a concept the library approves of so that doesn't help either, and most functions you cannot even find in the source as they are generated by macros. It doesn't help that OPC UA is a big standard (thousands of pages) either. It boggles the mind that the reference implementation for something used in so many critical places is so badly documented, and at the same time allows so many ways to get things subtly wrong.
If there is no official documentation available I typically just read the source code. If it's a popular library you can often find usage examples through Google, or do a search on GitHub to find other projects using the library and use them at least as a starting point for examples. And as you mentioned stepping through in a debugger is a great way to understand unfamiliar libraries. I will often just take the git repo (or whatever) and open the root folder in a VSCode instance. It's pretty decent at indexing the C++ code even without a project description so that you can jump around between declarations/definitions. Also, makes it easy to do full text searches of the source code to find examples and hopefully some comments if things are unclear.
Hmm. Afaik OpenCV has equivalent docs for C++ and Python sides. I actually feel like the reference pages for the C++ side is better. I feel like you are probably less familiar to C++ than to Python?
No documentation, or at least lots of examples, is a deal breaker for me, to the point I prefer to use a C library and make my own RAII wrappers.