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
I am having a good experience with Sublime Text, but I am missing some features of Eclipse, like code generation. Is it possible in Sublime to generate simple code, like props, constructors etc?
upd i mean not just generate a method signature like ToString(), but autoadd all fields in it.
I'm pretty sure that you can improve your experience on Sublime by using the "Snippets" feature.
As mentioned earlier, there are some "ready-to-use" Snippets
But you can always build your own (that might suit your needs in a better way). Here's the official documentation from Sublime: http://docs.sublimetext.info/en/latest/extensibility/snippets.html
p.s: The question is tagged C#, but the author mentions Eclipse.. God, I didn't know that such thing was possible.. but it is: how to configure Eclipse for C#
I could not find anything about on the net and i´m quite clueless to the XML comment support in doxygen.
My problem is as simple as this:
/// <see cref="GenericClass{TTypeparam}"/>
Which seems to me to be the correct way to reference an open generic in XML comments, does not produce a link in the doxygen output. It just copies the text from the cref attribute to the output.
I know that linking to generics works in doxygen from custom pages by using GenericClass<TTypeParam>. So is this a known bug, or did i miss something obvious?
Btw. I´m using doxygen 1.8.2
Doxygen does not support the { .. } syntax inside cref at the moment. You could regard this as a bug. Feel free to submit a bug report in doxygen's bug tracker for this.
Doxygen just doesn't seem to have a good way to handle generics at the moment (in 1.8.8) - unless you're happy to forget the standard Microsoft-supported XML format (which uses {...} syntax) and switch to using "GenericClass" or "\ref GenericClass" (both of which are of course invalid XML that the Visual Studio tooling won't like).
See doxygen bugs https://bugzilla.gnome.org/show_bug.cgi?id=738173, https://bugzilla.gnome.org/show_bug.cgi?id=738167 and https://bugzilla.gnome.org/show_bug.cgi?id=704090
What tools have you used to create class source code from xml files? Is this an edge case that I need to roll my own? I have need to create DTOs from some XML files, but the XML files are subject to change (add/remove attributes) so I need to be able to quickly update them.
I'm reallly not impressed with the .xml -> .xsd -> bloated .cs approach, and was looking for something to hopefully generate simple POCOs for me. Are there any tools you've used or seen that do this?
There is a built-in way to do this in VS2008 and later, T4. Hanselman has a bunch of great links in one place.
How about Xsd2Code:
http://xsd2code.codeplex.com/
T4 sounds perfect for this.
It's essentially an ASP.NET like syntax to generate code based on your template.
You would write the template to output the code for the POCO as needed, and then embed code in the template to iterate over your XML collection.
T4 is part of Visual Studio 2008 (but undocumented), and 2010. The Microsoft DSL tools gives support for T4 for Visual Studio 2005 as a separate download.
http://msdn.microsoft.com/en-us/library/bb126445.aspx
I realise that this is a rather old post and you have probably moved on.
But I had the same problem as you so I decided to write my own program.
It is in no way elegant but it did the job for me.
You can get it here: Please make suggestions if you like it.
SimpleXmlToCode
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 2 years ago.
Improve this question
Which parsers are available for parsing C# code?
I'm looking for a C# parser that can be used in C# and give me access to line and file informations about each artefact of the analysed code.
Works on source code:
CSParser:
From C# 1.0 to 2.0, open-source
Metaspec C# Parser:
From C# 1.0 to 3.0, commercial product (about 5000$)
#recognize!:
From C# 1.0 to 3.0, commercial product (about 900€) (answer by SharpRecognize)
SharpDevelop Parser (answer by Akselsson)
NRefactory:
From C# 1.0 to 4.0 (+async), open-source, parser used in SharpDevelop. Includes semantic analysis.
C# Parser and CodeDOM:
A complete C# 4.0 Parser, already support the C# 5.0 async feature. Commercial product (49$ to 299$) (answer by Ken Beckett)
Microsoft Roslyn CTP:
Compiler as a service.
Works on assembly:
System.Reflection
Microsoft Common Compiler Infrastructure:
From C# 1.0 to 3.0, Microsoft Public License. Used by Fxcop and Spec#
Mono.Cecil:
From C# 1.0 to 3.0, open-source
The problem with assembly "parsing" is that we have less informations about line and file (the informations is based on .pdb file, and Pdb contains lines informations only for methods)
I personnaly recommend Mono.Cecil and NRefactory.
Mono (open source) includes C# compiler (and of course parser)
If you are going to compile C# v3.5 to .net assemblies:
var cp = new Microsoft.CSharp.CSharpCodeProvider(new Dictionary<string, string>() { { "CompilerVersion", "v3.5" } });
http://msdn.microsoft.com/en-us/library/microsoft.csharp.csharpcodeprovider.aspx
If you're familiar with ANTLR, you can use Antlr C# grammar.
I've implemented just what you are asking (AST Parsing of C# code) at the OWASP O2 Platform project using SharpDevelop AST APIs.
In order to make it easier to consume I wrote a quick API that exposes a number of key source code elements (using statements, types, methods, properties, fields, comments) and is able to rewrite the original C# code into C# and into VBNET.
You can see this API in action on this O2 XRule script file: ascx_View_SourceCode_AST.cs.o2 .
For example this is how you process a C# source code text and populate a number of TreeViews & TextBoxes:
public void updateView(string sourceCode)
{
var ast = new Ast_CSharp(sourceCode);
ast_TreeView.show_Ast(ast);
types_TreeView.show_List(ast.astDetails.Types, "Text");
usingDeclarations_TreeView.show_List(ast.astDetails.UsingDeclarations,"Text");
methods_TreeView.show_List(ast.astDetails.Methods,"Text");
fields_TreeView.show_List(ast.astDetails.Fields,"Text");
properties_TreeView.show_List(ast.astDetails.Properties,"Text");
comments_TreeView.show_List(ast.astDetails.Comments,"Text");
rewritenCSharpCode_SourceCodeEditor.setDocumentContents(ast.astDetails.CSharpCode, ".cs");
rewritenVBNet_SourceCodeEditor.setDocumentContents(ast.astDetails.VBNetCode, ".vb");
}
The example on ascx_View_SourceCode_AST.cs.o2 also shows how you can then use the information gathered from the AST to select on the source code a type, method, comment, etc..
For reference here is the API code that wrote (note that this is my first pass at using SharpDevelop's C# AST parser, and I am still getting my head around how it works):
AstDetails.cs
AstTreeView.cs
AstValue.cs
Ast_CSharp.cs
We have recently released a C# parser that handles all C# 4.0 features plus the new async feature: C# Parser and CodeDOM
This library generates a semantic object model which retains comments and formatting information and can be modified and saved. It also supports the use of LINQ queries to analyze source code.
You should definitely check out Roslyn since MS just opened (or will soon open) the code with an Apache 2 license here. You can also check out a way to parse this info with this code from GitHub.
http://www.codeplex.com/csparser
SharpDevelop, an open source IDE, comes with a visitor-based code parser which works really well. It can be used independently of the IDE.
Consider to use reflection on a built binary instead of parsing the C# code directly. The reflection API is really easy to use and perhaps you can get all the information you need?
Have a look at Gold Parser. It has a very intuitive IU that lets you interactively test your grammar and generate C# code. There are plenty of examples available with it and it is completely free.
Maybe you could try with Irony on irony.codeplex.com.
It's very fast and a c# grammar already exists.
The grammar itself is written directly in c# in a BNF like way (acheived with some operators overloads)
The best thing with it is that the "grammar" produces the AST directly.
Something that is gaining momentum and very appropriate for the job is Nemerle
you can see how it could solve it in these videos from NDC :
Igor Tkachev - Metaprogramming with Nemerle
Igor Tkachev - Nemerle Programming Language
Not in C#, but a full C# 2/3/4 parser that builds full ASTs is available with our DMS Software Reengineering Toolkit.
DMS provides a vast infrastructure for parsing, tree building, construction of symbol tables and flow analyses, source-to-source transformation, and regeneration of source code from the (modified) ASTs. (It also handles many other languages than just C#.)
EDIT (September) 2013: This answer hasn't been updated recently. DMS has long handled C# 5.0
GPPG might be of use, if you are willing to write your own parser (which is fun).