Documenting Your .NET Assemblies with Blazorade Xml Docs
This is a very typical case where one thing lead to another. Earlier this year, before the world went haywire, me and Evan were throwing ideas about documenting Blazorade Bootstrap with Blazorade Bootstrap. Evan is the guy who joined the Blazorade team and whom I wrote about in an earlier article.
I guess the original idea was to replace the Blazorade Bootstrap Wiki with some kind of site that we would have built with Blazorade Bootstrap. I noticed quite early that the wiki documentation started to drift out of sync with the actual implementation. This happened already before we published the first version of Blazorade Bootstrap. So we had to figure out something to fix that. By leveraging XML documentation comments, we get a lot of help from the C# compiler. This helps keeping the documentation in sync with the implementation quite a lot.
Blazorade XML Docs is Born
My idea with Blazorade has always been to have it as an umbrella for component libraries and related tools to help building Blazor applications. So it was quite a natural step to create Blazorade XML Docs as a separate library, that you too can use to create documentation for you .NET libraries as Blazor applications. Blazor WebAssembly applications work pretty well for documenting .NET libraries. And with the Progressive Web App (PWA) option, you can even offer your documentation for offline use. That’s what I did with blazorade.com too. It is a Blazor WebAssembly application built with the Blazorade XML Docs and Blazorade Bootstrap libraries, with the PWA option turned on.
The only thing I needed to make the application completely work offline too, was to check the PWA checkbox when creating the project, and adding *.svg files to the list of offline assets. This I wrote about in this previous article.
What is Blazorade XML Docs?
So what is Blazorade XML Docs then? It is actually two libraries.
Blazorade.XmlDocumentation– This is a .NET Standard 2.1 class library that exposes functionality for parsing XML documentation files generated by the C# compiler.Blazorade.XmlDocumentation.Components– UsesBlazorade.XmlDocumentationandBlazorade.Bootstrapto create Blazor components that you can use to document your .NET libraries with.
These two libraries are currently very much being worked on, so there might be changes coming before v1.0 is available. But you are welcome to try them out. Both of these libraries are available as preview versions on Nuget.org.
The source code is available on GitHub, together with the rest of the Blazorade source code.
Summary
To get started with Blazorade XML Docs, clone the repository and have a look at the DocsTestApp. It is a Blazor Server application that uses Blazorade XML Docs to produce documentation for Blazorade XML Docs.
I will write another article on how to create your own documentation applications, so stay tuned for more!
0 Comments