Develop Reference

Ways to document math formulas for C# projects

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

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.
https://marketplace.visualstudio.com/items?itemName=vs-publisher-1305558.VsTeXCommentsExtension (for VS 2017, 2019)
https://marketplace.visualstudio.com/items?itemName=pierreMertz.TeXcomments (works with VS 2010)
For VS 2022 there is new version of the first extension:
https://marketplace.visualstudio.com/items?itemName=vs-publisher-1305558.VsTeXCommentsExtension2022

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

C# code builder/formatter

Does anyone know of a library which helps with generating C# code? For example, if I need to generate a *.cs file containing the definition of a class, I'd like to be able to specify the class and method bodies using an object tree (similar to expression trees) and then tell the library to give me well the formatted C# code as a string.
Thanks.

Have you looked at Microsoft.CSharp.CSharpCodeProvider?
Provides access to instances of the C# code generator and code compiler.

There are many tools for code generation and they are listed below:
Code Smith
codesmithtools dot com
codegeneratorpro dot com
etc
Code generators may sound like saving a lot of time, in reality it depends on the kind of project your working on.
Look into System.CodeDom and CSharpCodeProvider.

I'm rather fond of Terance Parr's StringTemplate. It's at the core of the compiler building tool ANTLR — StringTemplate is responsible for for code generation, allowing ANTLR to target just about any language for its compilers.
You can download the latest C#/.Net port from http://www.stringtemplate.org/download.html
You can read about string template in these papers by Dr. Parr:
[DRAFT] A Functional Language For Generating Structured Text
Enforcing Strict Model-View Separation in Template Engines
More at http://www.stringtemplate.org/article/list
CodeProject has an article on code generation with StringTemplate as well: http://www.codeproject.com/KB/codegen/DotNetCodeGeneration.aspx

Code generation tool targeting C++ and C#

I have a set of applications that are being built using a combination of C# and C++. We have a set of shared objects between the two languages, and rather than define each one separately in each language, I would prefer to use a code generation tool. Ideally such a tool would be FOSS, although that's not an absolute requirement. The objects themselves are relatively simple, although there is inheritance from baseclasses, implementation of interfaces, containment of other object types, and collections of other object types.
The C++ target environment is Visual C++ 2008.
Does anyone have any recommendations for a tool that can handle this kind of task?
Example code:
public class Tax
{
private static Dictionary<string, double> _TaxRates;
public Dictionary<string,double> TaxRates { get { return _TaxRates; } }
}

For any code generation problem I'd take a good look at T4 (the text templating functionality that appeared in VS.NET 2008).
A good place to start with T4 is...
http://www.hanselman.com/blog/T4TextTemplateTransformationToolkitCodeGenerationBestKeptVisualStudioSecret.aspx
You would need different templates for C++ and C#, and would drive your code generation from some other metadata.
The alternative is to use the CodeDom API. This has two CodeDomProviders (CppCodeProvider and CSharpCodeProvider) that can target each language.
For more information:
http://msdn.microsoft.com/en-us/library/system.codedom.compiler.aspx
There's a related links on SO:
T4 vs CodeDom vs Oslo
Is it possible to dynamically compile and execute C# code fragments?

cog is a code-generation tool that lets you embed code-generation python code in your C++/C# files. Its advantage is that it's really easy to use, especially if you already know python.

Google Protobuf might one of the best solution available for free.
See the language page.

You can also investigate CodeSmith. You can write templates in asp.net like language to generate any sort of code.

The .Net classes for emitting source code, for example the GenerateCodeFromCompileUnit method of the CodeDomProvider base class, can be used to emit source code in various languages from a single definition: for example, there's a CppCodeProvider as well as a CSharpCodeProvider. It may only be managed C++, but you did say "relatively simple".

The way I've done this multiple times is to define my own LL language and parse it, and have it generate class definitions in either language, OR write the class definitions in one target language, and then parse them to generate the other language.

I can highly recommend using Ruby as a code generator tool.
It is easy to create internal DSL's in Ruby and to generate code from it.
I use Ruby every day to generate both C++ and C# code. It has dramatically reduced the time I need to write the boring/tedious part of the application.

Existing library to calculate code complexity of a block of code

I'm given a string which contains an arbitrary amount of code. I want to calculate a number which represents the code complexity of that string. Something like:
int complexity = Lib.FindComplexity(someString);
I realize there are a lot of tools out there that will do this for you. These tools will not work for me, because I want to do it programmatically. I'd love for the library to be in C#, but will work with anything at this point.
Thanks in advance!

Have you considered using one of those existing tools and wrapping it in a library? For instance, you might be able to use the NDepend.Console.exe by calling it from your code with the parameters you want, and parse out the result.

NDepend is a great tool, although not cheap at the time I looked at it. If money isn't an option, I'd look into using reflection and http://en.wikipedia.org/wiki/Cyclomatic_complexity. It doesn't meet your requirement with any string but you could definitely test assemblies you created.

You can also use reflector and the code metrics plug-in available for it.

A library such as this must be able to parse an arbitrary language
fragment, and then compute the complexity metrics over the parsed fragment.
Most metrics tools have at best a parser for the entire language,
not just a fragment, so you are likely to be hard pressed to find
many solutions.
There is one system that can provide you what you need:
our DMS Software Reengineering Toolkit. It provides parsers
for many languages (such as Java and C#;
it is unclear what language you want to analyze).
DMS has been used already to implement these kinds of metrics
for several langauges (Java, C#, JavaScript, COBOL)
and the process of doing this is straigtforward.
And DMS does parse langauge fragments, and amazingly,
the metrics implementation actually operate on such fragments.
You could customize DMS to implement exactly what you want.
See http://www.semanticdesigns.com/Products/DMS/DMSToolkit.html
and for derived metrics tools,
http://www.semdesigns.com/Products/Metrics/index.html

Constructing a simple interpreter

I’m starting a project where I need to implement a light-weight interpreter.
The interpreter is used to execute simple scientific algorithms.
The programming language that this interpreter will use should be simple, since it is targeting non- software developers (for example, mathematicians.)
The interpreter should support basic programming languages features:
Real numbers, variables, multi-dimensional arrays
Binary (+, -, *, /, %) and Boolean (==, !=, <, >, <=, >=) operations
Loops (for, while), Conditional expressions (if)
Functions
MathWorks MatLab is a good example of where I’m heading, just much simpler.
The interpreter will be used as an environment to demonstrate algorithms; simple algorithms such as finding the average of a dataset/array, or slightly more complicated algorithms such as Gaussian elimination or RSA.
Best/Most practical resource I found on the subject is Ron Ayoub’s entry on Code Project (Parsing Algebraic Expressions Using the Interpreter Pattern) - a perfect example of a minified version of my problem.
The Purple Dragon Book seems to be too much, anything more practical?
The interpreter will be implemented as a .NET library, using C#. However, resources for any platform are welcome, since the design-architecture part of this problem is the most challenging.
Any practical resources?
(please avoid “this is not trivial” or “why re-invent the wheel” responses)

I would write it in ANTLR. Write the grammar, let ANTLR generate a C# parser. You can ANTLR ask for a parse tree, and possibly the interpreter can already operate on the parse tree. Perhaps you'll have to convert the parse tree to some more abstract internal representation (although ANTLR already allows to leave out irrelevant punctuation when generating the tree).

It might sound odd, but Game Scripting Mastery is a great resource for learning about parsing, compiling and interpreting code.
You should really check it out:
http://www.amazon.com/Scripting-Mastery-Premier-Press-Development/dp/1931841578

One way to do it is to examine the source code for an existing interpreter. I've written a javascript interpreter in the D programming language, you can download the source code from http://ftp.digitalmars.com/dmdscript.zip
Walter Bright, Digital Mars

I'd recommend leveraging the DLR to do this, as this is exactly what it is designed for.
Create Your Own Language ontop of the DLR

Lua was designed as an extensible interpreter for use by non-programmers. (The first users were Brazilian petroleum geologists although the user base has broadened considerably since then.) You can take Lua and easily add your scientific algorithms, visualizations, what have you. It's superbly well engineered and you can get on with the task at hand.
Of course, if what you really want is the fun of building your own, then the other advice is reasonable.

Have you considered using IronPython? It's easy to use from .NET and it seems to meet all your requirements. I understand that python is fairly popular for scientific programming, so it's possible your users will already be familiar with it.

The Silk library has just been published to GitHub. It seems to do most of what you are asking. It is very easy to use. Just register the functions you want to make available to the script, compile the script to bytecode and execute it.

The programming language that this interpreter will use should be simple, since it is targeting non- software developers.
I'm going to chime in on this part of your question. A simple language is not what you really want to hand to non-software developers. Stripped down languages require more effort by the programmer. What you really want id a well designed and well implemented Domain Specific Language (DSL).
In this sense I will second what Norman Ramsey recommends with Lua. It has an excellent reputation as a base for high quality DSLs. A well documented and useful DSL takes time and effort, but will save everyone time in the long run when domain experts can be brought up to speed quickly and require minimal support.

I am surprised no one has mentioned xtext yet. It is available as Eclipse plugin and IntelliJ plugin. It provides not just the parser like ANTLR but the whole pipeline (including parser, linker, typechecker, compiler) needed for a DSL. You can check it's source code on Github for understanding how, an interpreter/compiler works.