15 ms·
In code documentation doesn't support such thing. And documentation outside of code suffers from rot.
by whatevaa 1y ago
In code documentation doesn't support such thing. And documentation outside of code suffers from rot.
- rmunn 1y agoSome 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-reference/xmldoc/recommended-tags#generate-links-and-references 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.
- account42 1y agoWe 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.