And then there is Microsoft's annoying habit of creating APIs which return the information you actually need . . . nested three levels deep inside a bunch of their own custom data structures.

I've basically resigned myself to "it makes sense in Redmond somehow, even if it makes no sense to me."

> But to find out what the default options actually are, you have to find another page, probably the FooOptions constructor. I wanted the default options to be mentioned on the "Foo(string parameter)" page, and they so rarely are.

It's better for maintenance (of the documentation) if the default options are only described in one place. (If the defaults change in a new version, this ensures the documentation doesn't have inconsistent, wrong descriptions. The analogous reasoning, applied to the code, is probably part of why the FooOptions class exists in the first place, after all.) But they should do you the courtesy of linking there.

In some fairness, the page existing at all is half the battle. I'm glad the canvas exists for the paint to eventually, maybe, one day arrive.

In similar cases (maybe not exactly here), I suspect the author also didn't know and didn't care to look it up and just wanted to tick the box that it's now documented.

This is why I rage against the crowd that promotes "self documenting code". There's no such thing, even if you should strive to make your code as readable as possible. But if there's a way to misinterpret it then you can bet many people will.

The biggest problem is that this ends up creating so much extra work. An extra 2 seconds from the dev could save hundreds or even thousands of people hours of work. I can't tell you how many hours I've spent chasing stupid shit like your example. I don't know a single programmer who hasn't.

I just don't understand why everyone's frustration with documentation (or lack of) doesn't make obvious the importance of good documentation. Every single one of us has experienced the wasted time and effort that results from the lack of documentation or from low quality docs. Every single one of us has also reaped the benefits of good documentation and seen how much faster it makes us. How does anyone end up convincing themselves that documentation is a waste of time? It feels insane

That's more about API design than about documentation though, as with a proper function name/using value objects/something else, you already know what the correct value to pass is.

It's a widespread issue though, where the API designer doesn't clearly communicate either what the thing does and/or what the thing needs.

This is why I'm sad that hungarian notation has gained into such a bad reputation. Sure, you can overdo it, but a `duration_ms` or a `response.size_bytes` or a `max_memory_mb`, or an `overhead_ns` is so much easier to use.

That’s just a C enum interfaced in Swift. You can’t instantiate it, and it has no methods or any kind of functionality. It’s effective a list of numbers.

What are you expecting the documentation to say here? It will make more sense when you find where it’s used.

Edit: First link on the bottom explains exactly what it’s used for. https://developer.apple.com/documentation/avfoundation/retri...

There are indeed languages that don't have the word "cousin" -- or "uncle" or "aunt".

> with Xcode, go to fargler settings click on narg screen

I hate how this looks "accessible" to people in theory, but in reality finding those screens is more like playing a hidden object game.

Also, I hate how those things keep changing around in all kinds of software, but especially Apple. Somebody probably thinks "yeah maybe we should move the Fargler settings from the Narg to the Birp screen", and makes dozens of internet "documentation" (and sometimes their own!) obsolete.

The more useful answer is:

a) it needs namespaces

b) but giving people namespaces is unironically bad because it's what lead to "enterprise development" style APIs like C# where everything is named System.DataStructures.Collections.Arrays.Lists.ArrayList, as if giving something a longer name makes it more professional.

c) so instead two letters means a system framework and three letters means a user framework

No, you missed the point. The problem isn't "narg" or "flargling" - those are just random stand-ins for normal words. Instead the problem is that the description says nothing that isn't already said by the symbol name. Whether or now you know what "narg" and "flargling" mean, a documentation page for Nargflargler that just describes it as "Flargles the narg" provides zero additional information to you.