5 ms·

I don't know why but I always find C/C++ libraries' documentation to be god awful to read compared to say Python or even JS libraries. An auto generated dump of

I don't know why but I always find C/C++ libraries' documentation to be god awful to read compared to say Python or even JS libraries. An auto generated dump of javadoc comments is a terrible introduction. For example, if I want to open an image [1], it shows what I need to build the plugin but it doesn't have any code samples on how to use it. The constructor requires an manager -- what's that? After importing, how do I get the texture buffer? I'm sure all of this info is somewhere on the docs but I shouldn't have to search for something that should all be on the same page. [1] https://doc.magnum.graphics/magnum/classMagnum_1_1Trade_1_1AnyImageImporter.html https://doc.magnum.graphics/magnum/classMagnum_1_1Trade_1_1A...

bogwog 4y ago
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.
- trinovantes 4y ago
  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
- mshockwave 4y ago
  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.
- mosra 4y ago
  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-python-bindings/#everyone-just-uses-sphinx-you 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.)
flohofwoe 4y ago
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 https://doc.magnum.graphics/magnum/pages.html (which arguably should be the main page)
mosra 4y ago
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_1SceneData.html https://doc.magnum.graphics/magnum/classMagnum_1_1Trade_1_1S... [1] https://doc.magnum.graphics/magnum/classMagnum_1_1Trade_1_1AbstractImporter.html#Trade-AbstractImporter-usage https://doc.magnum.graphics/magnum/classMagnum_1_1Trade_1_1A...

bogwog 4y ago

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.

trinovantes 4y ago
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
mshockwave 4y ago
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.
mosra 4y ago
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-python-bindings/#everyone-just-uses-sphinx-you 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.)

flohofwoe 4y ago

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 https://doc.magnum.graphics/magnum/pages.html (which arguably should be the main page)

mosra 4y ago

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_1SceneData.html https://doc.magnum.graphics/magnum/classMagnum_1_1Trade_1_1S... [1] https://doc.magnum.graphics/magnum/classMagnum_1_1Trade_1_1AbstractImporter.html#Trade-AbstractImporter-usage https://doc.magnum.graphics/magnum/classMagnum_1_1Trade_1_1A...