I’ve had the complete opposite experience. I’ve yet to use a non-trivial Python library/framework where I didn’t end up having to dig through the source code to figure out how to do something. The dynamic nature of the language makes it hard to auto generate useful docs. With something like Doxygen you can easily know exactly what types a function expects, how to construct those types, etc.

...OTOH, digging through Python source code is more pleasant than C++. So it balances out I guess.

While I'm here, a shameless self-promo -- Magnum uses a Python doc generator that includes type annotations by default, moving it closer to what you're used to from C++: https://blog.magnum.graphics/announcements/introducing-pytho...

(Sure, it still means the library has to make those annotations in the first place, and have them correct, but the newer and more complex libraries fortunately do, if even just to make IDE autocompletion work.)

same, C++ doc can be awful...if it's hand-written, but doxygen is quite good. On the other hand, docs for dynamic languages like javascript and python often hang me there with ambiguous descriptions like "string-like" or "buffer-like" -- yes, I know what those descriptions _mean_ but that doesn't really give me enough confidence to use those APIs.

Which python libs do you find insufficiently documented? Admittedly I've only used Python for quick scripts or apps (bs4, fitz, flask) rather than my primary language so maybe my view is somewhat biased

Hah, good point, seems like this class suffers from documentation erosion. It got expanded and expanded and expanded and the essential piece of information got somehow lost down there in the gory details. The actual usage info and code snippet is in the base class documentation [1], it's just that it's no longer linked as prominently as it should be. I'll fix that.

It's not this bad everywhere tho, docs of fresher APIs didn't have a chance to erode yet: https://doc.magnum.graphics/magnum/classMagnum_1_1Trade_1_1S...

[1] https://doc.magnum.graphics/magnum/classMagnum_1_1Trade_1_1A...

Magnum's documentation is top tier IMHO. Just don't start with the API reference, but with this page: https://doc.magnum.graphics/magnum/pages.html

(which arguably should be the main page)