C# XML documentation: dealing with the entirety

Question

In recent times I annotated my entire large C# project with XML documentation, and I also made heavy use of the inheritdoc notation (for example when we are overriding a base class method). Imagine my surprise and horror when I looked at the resulting XML and found that it actually said "inheritdoc". That is: the XML didn't inherit the text (the whole point of doing this) but just put an inherit element in there.

As a small-time nerd who wants to do my own XML-to-HTML conversion: how can I make it actually copy the text (as inheritdoc suggests)? I can't understand the meaning of inheritdoc in an XML file, because (given the C# source code, and complicated rules around types and parsing) you might be able to determine what inherits from what, but given the XML alone, you have no clue.

I just want an XML file with all my comments, and where I wrote 'inherit' in the source, I want that text copied in the docs output. Wow!

We used /// <inheritdoc /> since many years and the output created by Sandcastle is as expected a copy of the original documentation — Klaus Gütter
– Klaus Gütter, Commented Jan 10 at 5:46
Try to distance yourself from your favourite tools and "Sandcastle" Perhaps you could look at how Sandcastle handles it and copy that same approach for your homebrew? — mjwills
– mjwills, Commented Jan 10 at 6:21
The generated XML doc file contains exactly what it should: your XML comments. It's nowhere written that the comments will be processed there. Further processing is the task of other tools. For example, VS IntelliSense does it and the <inheritdoc> tags are resolved in the quick info. Similarly, Sandcastle, VSdocman (I'm the author) and other tools will resolve these and other tags, such as <include>, in the generated documentation. If you want to create your own XML to HTML conversion tool, which is exactly what Sandcastle and VSdocman do, you need to handle these cases yourself. — Peter Macej
– Peter Macej, Commented Jan 10 at 7:54
You wrote: because (given the C# source code, and complicated rules around types and parsing) you might be able to determine what inherits from what, but given the XML alone, you have no clue. Exactly. That's why all other tools, including IntelliSense, need to have also the source code or compiled DLL. — Peter Macej
– Peter Macej, Commented Jan 10 at 7:57

equin0x80 · Accepted Answer · 2025-01-25 00:17:18Z

0

The consensus answer seems to be to use Sandcastle (a bit strange to me, as a third-party product; one might have expected Microsoft to provide the entire toolchain). But I will accept the consensus and try it! Thanks.

I also now understand that the XML output isn't intended to be the be-all-and-end-all, but rather we should go back to the tools (compiler etc) if we need something more detailed.

edited Jan 25 at 0:17

answered Jan 25 at 0:08

equin0x80

3331 silver badge10 bronze badges

Sign up to request clarification or add additional context in comments.

Collectives™ on Stack Overflow

C# XML documentation: dealing with the entirety

1 Answer 1

Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

Comments

Your Answer

Sign up or log in

Post as a guest

Related