This is just one example of how metrics can distort things, of course. Someone in management said "We want 100% documentation coverage of every method," so the staff dutifully wasted everyone's time by writing "setDefaultOptions: sets the default options". It's the kind of thing an LLM could have done better, and if you know my opinion of LLM's, you'll know that's damning with faint praise.
My own bete noire here is MSDN. It's full of overloads like "Foo(string parameter, FooOptions options) - actually useful documentation. Foo(string parameter) - does Foo with default options." 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. (A few pages are better, thankfully).
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."
Microsoft's APIs basically shove all the implementation details onto the API user. This is, of course, abysmal API design, but "tasteful design" (in any sense) and "Microsoft" have never been in the same building. But it does make sense. And it also tells you how to interact with Microsoft APIs: the same way you interact with the hardware details that assembly languages export to the user, namely through a wrapper. (But, taste is difficult to find; that wrapper might have imbibed some Microsoft "design" by virtue of being exposed to too much Microsoft.)
Rant: if you want antialiased text, you need to use Direct2D. Direct2D is one of those APIs that waste developer's lives. You have to allocate your own framebuffer, for crying out loud. And then, you have to reallocate it if it ever disappears for some reason, and the docs don't tell you when this might happen (hot swap a video card? change monitor resolution? User moves window to a monitor with a different video card?).
I found this out developing a cross-platform UI library, https://github.com/eightbrains/uitk, leading to my above conclusion that the only proper way to relate to the Microsoft API is through some layer.
> 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.
This is only a problem if you write it twice. Instead you can write it once and display it twice.
Hell, I even do this on my github.io website that uses markdown. You can just write some text in one document and read it in another.
We're programmers, so we should be lazy. It's about being the right lazy. You can be lazy by putting of a task today that takes more effort tomorrow or you can be lazy by doing a task today that takes less work than it would take to do tomorrow. Most people choose the former and wonder why they have so much work. In programming if you're doing redundant work then you're probably being the first type of lazy
In code documentation doesn't support such thing. And documentation outside of code suffers from rot.
Some varieties of in-code documentation do support links, e.g. XmlDoc which is the de facto standard for documenting C# code (and therefore the most relevant to my comments about MSDN because I was referring specifially to the .NET API documentation) has multiple ways of embedding links in your in-code documentation comments: https://learn.microsoft.com/en-us/dotnet/csharp/language-ref...
MSDN even uses those, a lot. But not enough. I wish that every time they had a "Foo(string parameter) - uses the default FooOptions" it was a link to the documentation section where the default FooOptions are listed. But usually you're left to find the default FooOptions yourself, which means 5-10 minutes of digging through docs (1-2 minutes if you're lucky) that I could have spent writing or reviewing code instead. That adds up.
We are talking about MSDN not some source files. Even if those pages are generated from in-code documentation that generation step can use whatever transclusion mechanisms Microsoft wants to add.
But that could be linked up rather than have you fumble through to find them.
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.