I've been using DocFX to generate code documentation for C# and for the most part found a lot of success with it. The articles are flexible and I really like that I can use markdown to maintain them while having them live side by side with the API references. I have also already spent the time documenting walkthroughs in Markdown and building a CI pipeline.
The problem I am trying to solve is that I need to figure out a way to get my code documentation (xml comments) output to be markdown instead of html so that it can be hosted by markdown wiki solution, specifically Azure DevOps (aka TFS). Azure DevOps Wiki seems to be very similar to gh-pages from GitHub as well, so I'm interested in similar solutions that I might be able to get to work in Azure DevOps. DocFX doesn't solve this problem because the output is .html instead of markdown.
All of Microsoft's documentation is focused on writing documentation by hand. I'm interested in generating documentation based on the xml comments in the code.
It looks like its a long open request on DocFx.
This alternative solution was recommended in a couple of places that I saw XmlDocMarkdown.
A console app that generates Markdown from .NET XML documentation comments.
Or you could always go with Pandoc. Either using the stock conversion, or roll your own custom LUA filter for the conversion process.
I've been using Swagger recently for a WebAPI project, and I like the documentation and its inclusion of the XML Documentation I put on my methods. I have various other non-WebAPI project that I'd like to generate documentation for. I know sandcastle exists, and I've used it previously, but it isn't maintained anymore. There is a fork that is maintained (the fork doesn't appear to be much of a change over the original). Additionally, it isn't the "prettiest" thing on the planet to use (or what it generates). Previously I used the output and Google promptly down-ranked me for not supporting mobile content.
Are there any other documentation generators that make modern websites that scale nicely on a desktop and mobile devices? Am I just relegated to making the documentation manually?
This is similar to How to create website from XML documentation comments?, however, that is four years old and as we all know, a lot of changes in technology in 4 years. I'm looking for current information.
DocFX makes it very easy to combine generated and manual documentation
https://dotnet.github.io/docfx/
It was developed by Microsoft for the replacement of the MSDN documentation portal, and made open source.
I'm not sure if the title is accurately describing what I'm trying to ask...
Basically, how does Visual Studio look at a code file in a CSPROJ and determine references for a method or variable, or if a using statement is not being used in the code? Obviously it's not just doing simple text parsing, and it seems to work before ever doing a build so I don't think it's referencing the assembly/CLR.
Is there an API that I can tie into from an external app, if I have the user select their CSPROJ or SLN file and be able to report on unused using statements in files, or methods/vars that aren't being called anywhere in their code?
I'm asking because I'm considering building some sort of reporting tool to show areas where code cleanup could occur, but I'm not really sure where to begin.
Thanks!
EDIT: As a followup question, is there a similar tool already out there?
Visual Studio does compilation on the fly, in order to determine many of the things like this, in addition to providing functionality like Intellisense.
Right now, the compilers are all a "black box" and not directly usable. The Roslyn project has the goal of changing this, allowing the full breadth of code analysis being done to be usable. It's currently in a CTP, and could be used now.
EDIT: As a followup question, is there a similar tool already out there?
Many third party extensions, such as Resharper, provide much of this functionality (such as their Safe Delete refactoring and Solution Wide Inspections).
I'm developing a TypeScript code generator that will use custom attributes on C# classes to generate TypeScript definitions and code files.
I'm considering two options for TypeScript code generation / source file analysis:
Reflection on compiled assemblies
Roslyn CTP
The tool would use custom attributes on properties and methods to generate a TypeScript file. Right now I'm not planning to convert the C# method body to JavaScript, but in the future this may be done. So for this reason I am seriously considering Roslyn. However to simply generate the outline of my TypeScript classes I think I could use reflection and custom attributes.
I am wondering:
a) Does Roslyn provide functionality that is impossible with Reflection? My understanding is that I cannot get method bodies with Reflection.
b) Would the Roslyn CTP license prevent my from distributing the tool under an open source license? This is not clear to me after reading the license
I just did something along these lines - works great for creating your datamodel in Typescript from your c# classes. I built it to generate a single AMD-module with an interface which mimics the basic data of your Models. Also supports Generics, and creates a class with Knockout properties, including a toJS() method and an update(data:Interface) method to update your class.
The whole thing is just a single T4 template. If anyone finds this and is interested: http://spabuilder.wordpress.com/2014/07/31/generating-typescript-from-c/
Also honors [KeyAttribute] and [Timespan] attributes for data models if you are using data annotations.
I've been messing around with generating js, and I'm finding Reflection to be a better tool for this. I'm basically pointing my generator at the bin folder of the project which the metadata comes from. There might be some difficulties with loading all the needed assemblies, and caveats with versions of assemblies in the bin folder, and versions of the same assemblies that your generator project references. But once you get over all of this, which I did with minimal difficulty, Reflection is a lot easier to use, and more reliable.
With Roslyn, you are basically just parsing c#. Roslyn does this very well, but I'm hesitant to switch to it from Reflection. With reflection, you get metadata more reliably.
Let's say you want the Prefix property of a RoutePrefixAttribute that decorates a controller class. If you're parsing c#, you may have:
[RoutePrefix("stringliteral")] or [RoutePrefix(constantString)]. So, you have to worry about whether it's a literal or a constant expression, then find out how to get the value of a constant expression, worry about all the different ways in which you can pass parameters to an atatribute (for example, will this break your code: [RoutePrefix(Prefix="literal")]...
Once you're dealing with the actual runtime objects with reflection, everything is just easier. You have a nice RoutePrefixAttribute object, and you can go routePrefix.Prefix to get, reliably, the value of the prefix.
This is just one example of how doing things with Reflection is easier. It's the difference between gathering metadata from a set of c# objects in a type-safe way, and scraping data from c# code, albeit with a really nice scraping tool.
EDIT: Since writing this answer, I've bit the bullet and switched to Roslyn. It's fairly powerful once you get the hang of it, and I did find one big advantage: you can get a reference to the workspace from a visual studio plugin, and easily do all kinds of stuff within the plugin.
Update Nov, 2018
The accepted answer is valid because it's dated in Aprl,2013
Now roslyn is distributed under Apache License Version 2.0
excerpt from the license:
Redistribution.
You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You meet the following conditions:...
Roslyn have a number of nuget packages
Doesn't the license only forbid you personally from distributing the binaries? It doesn't forbid you from adding a dependency from your NuGet package to the Rosyln CTP NuGet package. You personally cannot deliver the bits, but you can have NuGet pull in Roslyn automatically.
So just avoid checking Rosyln source or binaries into your version control.
The Roslyn website not clearly states that:
The current license is for evaluation and preview purposes only and
does not allow redistribution of the Roslyn binaries. Sharing of
sample projects built on the Roslyn APIs is permitted, but sample
users must have either the Roslyn CTP or the Roslyn NuGet package
installed in order to build and run.
I wouldn't use the current Roslyn CTP - simply because there will be new versions in 2014 and those will bring many breaking changes for sure. So you might end up with totally deprecated code.
(There recently was a blog post on this by a MS team member, but I'm afraid I currently don't have the link at hand.)
EditThere's a good chance that Roslyn then will get a license that also permits for commercial use...
Update - July 2015
Roslyn is still in CTP, but their FAQ on GitHub is much more to the point:
For sample code or learning purposes, the recommended way to redistribute the Roslyn DLLs is with the Roslyn NuGet package: [url:Microsoft.CodeAnalysis|http://www.nuget.org/packages/Microsoft.CodeAnalysis].
So it appears that you still cannot redistribute the DLLs in finished products. The project will need to be open sourced and the solution will need a reference the NuGet package.
Original Answer (November 2012)
I don't believe you can distribute under open source.
6.DISTRIBUTABLE CODE. The software contains code that you are permitted to distribute in programs you develop if you comply with the
terms below.
6.c Distribution Restrictions you may not modify or distribute the source code of any Distributable Code so that any part of it becomes
subject to an Excluded License. An Excluded License is one that
requires, as a condition of use, modification or distribution,
the code be disclosed or distributed in source code form; or item
others have the right to modify it.
At first it sounds like you could do it if you just include the Roslyn binaries, but the Distributable Code definition specifically says "The software contains code..." and I believe that is what everything after is referring to.
To your other question, Roslyn isn't fully finished and is still Beta. I don't know exactly if it is currently in a state that allows it to handle your needs. That's something you may just want to spend a couple of hours tinkering with. I wouldn't think it had more functionality than what .NET currently allows. You can see what they recently added in September here and what is currently not implemented here.
For my experience using T4 generations based on reflection, as TypeLite does, is somehow simpler but has some drawbacks, like once the project depends on the classes that have been generated, regenerating them with a breaking change (renamed a class) will lead to a non compiling project so running the template again will output a blanck file and the user will have an hard time making everything compile again.
So, having the same need, i started experimenting with Roslyn, and it seems very promising, but i have many doubts on how to use it properly...
You can take a look at what i'm doing and maybe help me here: https://github.com/TrabacchinLuigi/RoslynExporter
I am developing an API for some application. And I need to attach there a script engine to make it possible to invoke API from script.
It would be quite nice to have autocomplete, syntax highlight and debug in scripts.
I have found this solution: http://www.codeproject.com/Articles/27744/Net-Script-Editor-C-Vb-net-Mini-IDE
But there are a lot of bugs.
Does anybody have any ideas of alternative solution?
LinqPad has many of the features you are looking for - some of them cost a small extra fee, but it's probably worth the fee!
http://www.linqpad.net/
Snippet Compiler is a nice tool.
You don't mention which language your scripts are in, but based on your other question about debuggers I'll assume you are using IronPython.
The most complete (free/open source) option that I've been able to find is SharpDevelop. It includes all of the features you've mentioned for IronPython as well as a debugger. It is open source and includes many useful extensibility points, so it should provide a good starting point to fix bugs and add additional language support if needed (provided your use conforms to its license terms).
If your situation requires use beyond what is provided by the LGPL then the best choice (though not standalone or free) is to extend Visual Studio (there's already an extension for IronPython though I'm unsure if it supports debugging).
It doesn't sound like you're looking to do much, if any, development of your own for this but if I'm misreading your question then there are some editor controls available that provide the features listed (and then some) for .NET (not exhaustive):
Scintilla.Net
AvalonEdit (used by SharpDevelop)
An example of a project that uses Scintilla.Net is Peter.
You can try with SharpDevelop .