2

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).

MSwiatek
  • 21
  • 2
  • There was a LaTex Plugin for Sandcastle but it seems to be discontinued. No idea if it still works. https://github.com/cuda/latex-sandcastle/ – Klaus Gütter Jan 28 '23 at 15:07

2 Answers2

1

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:

Daniel Delimata
  • 29
  • 5
  • Thanks! the plugin is very useful! Unfortunately it's not a tool that generates html documentation pages for our classes from the code, so i cannot accept it as a solution, but it's an important part for our team. The other devs that receive our binaries however needs documentation on how to use the objects we provide. From what i have researched myself si far Doxygen seems to be the best chance for this purpose. I am new here and my reputation score here is apparently too low so i'm blocked from upvoting your answer for now. – MSwiatek Jan 31 '23 at 22:47
0

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

Daniel Delimata
  • 29
  • 5
  • This doesn't resolve the need for a good documentation. Our code is already very readable and self explanatory apart from maybe some formula implementations which are easier to read in math formalism then in C#. We need Documentation for publicly exposed classes in our library so devs from another team can use intellisense help based on our xml-documentation when working with our objects. – MSwiatek Jan 29 '23 at 18:55
  • Also seeing a formula itself never explains which assumption went into its derivation, nor does it explain its limitations of applicability. Thus we want our documentation to contain links to papers and financial literature discussing the relevant context. Another issue with a huge code base is to even find the code parts for a problem you are looking for. For this there is an overarching wiki-style documentation and on the more detailed articles it wants to link to the code generated doc (which has to be made) so people know where to find the proper code with a description and context. – MSwiatek Jan 29 '23 at 18:57
  • So you need something like a plugin to VS with LaTeX formula renderer. Right? Unfortunately I have not seen anything similar. – Daniel Delimata Jan 30 '23 at 13:38
  • VS support would be really great, however i already settle for any documentation generator tool that handles C# and xml-tags well, supports Latext and isn't too difficult to setup. Wikipedia lists quite a few tools, but it seems quite a few are somewhat outdated while others missing (DocFX) and it's not clear how well they fit all those points. it takes quite some time to research each individually. – MSwiatek Jan 31 '23 at 00:19
  • I still think LiterateCS might be what you're looking for. From what I understand, it works in two modes. 1. Within markdown, there are fragments of C# code (the classic approach proposed by Knuth). From such files, pure C# is generated for building. 2. Within C# code comments, there is markdown (with LaTeX patterns, and as I understand also links), and from this, documentation pages are built. Unfortunately, the author has not shown a comprehensive example anywhere. The second mode is I think more useful in your case. I apologize if my statement could confuse or suggest code unreadability. – Daniel Delimata Jan 31 '23 at 23:42
  • From LiterateCS: "If you prefer incorporating documentation into code, you can write it inside comments. You don't need to use special syntax to annotate the documentation. Multi-line comment blocks surrounded with /* and */ will be extracted and included in the output. Single line comments starting with //, as well as XML comments, are treated as code by LiterateCS." The last statement is prohibitive, because all our documentation is in XML comments so that it is available for intellisense and other tools. – MSwiatek Feb 01 '23 at 01:09
  • I see. Have you considered two steps processing (1. extracting documentation 2. processing of extracted documentation) or adding some JS (e.g. MathJax) to templates? I mean that formulas may be left as they are (not interpreted) by the tool itself but may be rendered later by another tool or by some JavaScript. – Daniel Delimata Feb 01 '23 at 07:36
  • Not yet. VS however can extract xml documentation into a separate xml file, which other tools can use to generate documentation from. But you mean MathJax would allow to build the documentation into html using any tool for that but leaving the latex expression in a raw uninterpreted state and then apply MathJax script to finalize them? If something like that wouldn't be too complicated to setup, it sure would be an option. I'm not familiar with MathJax and how it works. – MSwiatek Feb 01 '23 at 23:05
  • Neither am I but as I understand it is just javascript which may be included in any HTML page. https://docs.mathjax.org/en/v2.7-latest/start.html – Daniel Delimata Feb 01 '23 at 23:53