Menu
I would like to create a documentation website from C# XML documentation comments.
An example from the Python community. This Scipy documentation is created from this python code using a tool named Sphinx.
Is anything like that possible for a C# project?
Example of XML documentation comments in a .NET project (not mine) https://github.com/haf/NodaTime/blob/master/src/NodaTime/Period.cs#L26
/// <summary>
/// Represents a period of time expressed in human chronological terms: hours, days,
/// weeks, months and so on. All implementations in Noda Time are immutable, and return fields
/// in descending size order: hours before minutes, for example.
/// </summary>
public sealed class Period : IEnumerable<DurationFieldValue>, IEquatable<Period>
Edit: The full extent of advice I could find in other questions was 'use Sandcastle'. As far as I can tell from its (ironically limited) documentation, it can only create Windows help files (.chm). Is that correct?
562
Enabling XML Comments XML comments are enabled by default in Visual Basic projects, and cannot be disabled. To enable or disable XML comments for a specific project, go to the project properties page, the Compile tab, and update the "Generate XML documentation file" checkbox.
C# documentation comments use XML elements to define the structure of the output documentation. One consequence of this feature is that you can add any valid XML in your documentation comments. The C# compiler copies these elements into the output XML file.
An XML comment encountered outside the document type declaration is represented by the Comment value syntax element. It contains the comment text from the XML message. If the value of the element contains the character sequence --> , the sequence is replaced with the text --> .
The XML comments are used to build API documentation which is readable by external tools. IntelliSense also reads these, and uses the contents to show the docs for your code in the assistance tooltips as you type (and in the Documentation window).
Edit: The full extent of advice I could find in other questions was 'use Sandcastle'. As far as I can tell from its (ironically limited) documentation, it can only create Windows help files (.chm). Is that correct?
No, that's not correct. Sandcastle can build a wide range of output.
However, these days you really want Sandcastle Help-File Builder (SHFB) which makes things a whole lot better. Still not entirely painless, but pretty good. The documentation for SHFB is generally pretty reasonable, too.
Funny you should give an example of Noda Time - SHFB is precisely what we use to generate our online API reference.
148
You could also try sharpDox. Another free and open source documentation generator. You are able to create html and chm output and soon word documents.
Here is an example for a html output.
P.S.: I am the creator of this tool.
4
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
