> 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.