I am working on a larger C# project in visual studio handling finance math, so naturally the code implements many special math formulas and they need to be properly documented. I am looking for a good way to produce a documentation from the code. Many objects already have some xml-doc comments with description setup and i am looking for ways to include math formulas written in latex into that.
What options are there and how easy are they to set up?
Or maybe more generally, are there better ways to produce such code documentation?
For me a few things are important:
- documenation must have a way to include math formulas.
- latex is our preferred syntax to write formulas
- ability to use cref-like links in documentation
- refactoring (like renaming a class) shouldn’t break the links between documentation and object.
- it should work with vs-intellisense tooltips and at least show the summary documentation of methods and classes
I tried using Doxygen 1.9.6 (we have also one C++ project) and I manged to make it partially work. it does render latex formulas from the summary tag, but it seems to have issues with certain C# things, for example i cannot make it to generate any documentation for (public) implementations of methods from generic interfaces regardless how i set up the configuration (need to do more research to what exactly is the problem).
2
Answers
Maybe Literate Programming is this what are you looking for. Literate programming is a programming paradigm where the documentation and the source code are written in a natural language, making the code easier to read, understand, and maintain. The source code is interspersed with explanations and descriptions that provide context and clarify the purpose and function of the code. This approach aims to make the code more accessible to a wider audience and to improve the overall quality of the code.
The general idea was introduced by Donald E. Knuth and implemented for C. (see http://www.literateprogramming.com)
Tommi Johtela proposed LiterateCS to implement it for C#. It assumes using markdown with LaTeX syntax for math formulas.
General introduction: https://johtela.github.io/LiterateCS/Introduction.html
Example of math formula in the generated documentation: https://johtela.github.io/LiterateCS/TipsAndTricks.html
I add this as a separate answer because it is completely different approach.
I have found another existing answer which may be helpful.
There are two extensions to VS which support LaTeX formula in comments.
For VS 2022 there is new version of the first extension: