So spoiled by Rust now when using one of these "documented" APIs.
* Rust's examples work, because the default behaviour of Rust's automated testing is to test your documented examples (as well as any unit tests you wrote), so, it's actually more effort to write examples that don't work. If you're too lazy for that, you're going to not write any examples, so then I at least know I'm in uncharted territory.
* The relevant Rust source code is linked. Mostly. Rust's source links don't chase macros, so it's conceivable your link tells you that foo(X) is just the result of the macro make_thing!(foo,X) and you need to chase how make_thing!() is defined which is annoying. But 99% of the time you discover immediately what's actually going on.
This week I would say about half of my time was spent fighting with the C# library for talking to the Microsoft Graph API. Both of which are, in theory, "documented" and yet I repeatedly ended up cribbing from Stack Overflow answers or, after beating my head against a wall, pasting URLs (which I already know will go stale in a year or two) and Microsoft's uselessly bland explanations for the obviously broken stuff as the excuse for why we can't do things you would obviously anticipate being possible.
Today I particularly liked: There are five documented ways to make an educationClass. Most of them simply don't work (unanswered Issues on github), and the error responses for these methods are undocumented and lead nowhere. But one of them does work. However the C# library drops the output of the API call for that method on the floor, presumably because coping with this case was hard, and so the best option (as a Stackoverflow post explains) is to reach inside the library, dredge out the HTTP request it's about to do, and perform that request yourself, then do all the heavy lifting they couldn't be bothered to do with the HTTP response to get what you actually wanted (including a polling loop because apparently nothing after the 1980s happened for Microsoft).
However, in the months since that Stackoverflow post was written, the C# library API has changed, enough that the example code wouldn't even build.
The change is undocumented (of course) and involves an enumeration (also undocumented) which was auto-generated for some reason. This feels like somebody was hoping it wouldn't matter if they changed it, and that somebody was wrong. But if they'd been forced to document it then maybe they'd have either decided it wasn't worth it (still works as before) or I'd have saved ten minutes guessing how the API now works.
But now it's the weekend and I'm going to write Rust.
A thing that helps with Rust, in my opinion, is that the language is statically typed and people mostly write functions. That makes it easy to glue the pieces together in my head. So even if the documentation isn't great, I can find a way to do what I want.
There's still lots of polymorphism in Rust. Take for example the way reqwest handles HTTP headers. Reqwest cares that it's technically possible (albeit a bad idea) to write arbitrary bytes into an HTTP header name even though those bytes are ASCII case crushed. This being understood, and Rust's strings necessarily being UTF-8 and not arbitrary bytes, a header's name might not be a string in Rust (though of course the vast majority are) and so Reqwest carries around a whole marker type for things-that-might-be-plausible-header-names, knowing that all any non-bad-guys will care about is a few simple ASCII strings but needing to correctly handle much more.
The two obvious things work, if you say the name of a header, you get that header, and there are constants like HOST defined for the most common headers to avoid typos, but you can do crazy stuff, and importantly if a hostile peer sends you crazy stuff Reqwest promises to cope.
Maybe it's that Rust's polymorphism is more explicit through Traits.
If Pigeon, Duck and Emu are all Birds, and further more Animals in C++ it's unclear what exactly this Bird superclass does for me, still less Animal or when I, knowing I have a Pigeon here, should consult the documentation for Bird and/or Animal rather than or in addition to that for Pigeon.
Whereas not only does the Emu not implement Fly, I can feel comfortable guessing that the code implementing Fly generically or for my Pigeon is unlikely to be related to my problem that this Pigeon says "quack" and I should instead look closely at the AnimalSound trait, given away by the fact I had to explicitly name that trait to get the "quack" noise from the pigeon.
* Rust's examples work, because the default behaviour of Rust's automated testing is to test your documented examples (as well as any unit tests you wrote), so, it's actually more effort to write examples that don't work. If you're too lazy for that, you're going to not write any examples, so then I at least know I'm in uncharted territory.
* The relevant Rust source code is linked. Mostly. Rust's source links don't chase macros, so it's conceivable your link tells you that foo(X) is just the result of the macro make_thing!(foo,X) and you need to chase how make_thing!() is defined which is annoying. But 99% of the time you discover immediately what's actually going on.
This week I would say about half of my time was spent fighting with the C# library for talking to the Microsoft Graph API. Both of which are, in theory, "documented" and yet I repeatedly ended up cribbing from Stack Overflow answers or, after beating my head against a wall, pasting URLs (which I already know will go stale in a year or two) and Microsoft's uselessly bland explanations for the obviously broken stuff as the excuse for why we can't do things you would obviously anticipate being possible.
Today I particularly liked: There are five documented ways to make an educationClass. Most of them simply don't work (unanswered Issues on github), and the error responses for these methods are undocumented and lead nowhere. But one of them does work. However the C# library drops the output of the API call for that method on the floor, presumably because coping with this case was hard, and so the best option (as a Stackoverflow post explains) is to reach inside the library, dredge out the HTTP request it's about to do, and perform that request yourself, then do all the heavy lifting they couldn't be bothered to do with the HTTP response to get what you actually wanted (including a polling loop because apparently nothing after the 1980s happened for Microsoft).
However, in the months since that Stackoverflow post was written, the C# library API has changed, enough that the example code wouldn't even build.
The change is undocumented (of course) and involves an enumeration (also undocumented) which was auto-generated for some reason. This feels like somebody was hoping it wouldn't matter if they changed it, and that somebody was wrong. But if they'd been forced to document it then maybe they'd have either decided it wasn't worth it (still works as before) or I'd have saved ten minutes guessing how the API now works.
But now it's the weekend and I'm going to write Rust.