We have a very old application dating back to ASP era which we are gradually refactoring to ASP.NET + VB.NET codebase.
It contains a lots of files with the below types:
aspx, asmx, ascx, vb, js (JavaScript), html, vbs (VBScript).
The backend database is SQL Server 2005 with lots of sprocs.
We would like to create a code documentation automatically generated from the comments in the code files. I liked Doxygen very much but seems like it does not support the above technologies. Can you please suggest some document generator tools, preferably a single tool or a group of tools?
Thanks a lot.
Ajit.
You can take a look at Microsoft's Sandcastle tool. I've used it many times, and it generates documentation based on the comments provided in your .NET code. If I remember correctly, it can also generate documentation for JavaScript libraries.
There are some out there:
SandCastle
NDOC
i've used SandCastle and it works too good if you have xml comments in your code.
You first enable xml documentation in your project by setting it in Project Properties -> Compile -> Generate XML Documentation.
Once done you may have to set treat warnings as errors, so that the studio can point out to you where and all the XML comments are missing.
To add an XML Comment, you place your cursor before a class definition or a function definition and type
///
This will automatically generate xml tags for documentation and then once you are done, you can import the project and start to build the documentation.
The good part is, if you have documented your classes well, when you use those functions in your application upon mouse over you can find the description which you wrote, much like how intellisense documentation works.
Let me know if you run into any other issues.
My last suggestion, make a hello world project and xml document it and get used to sandcastle with it.
Related
I am having trouble tracking down information regarding extending Intellisense. It looks like creating a plugin for VS 2010 or Resharper would do the trick. However, I can't find any documentation for adding items to the intellisense dropdown.
This post got pretty close: How to extend IntelliSense items?
But I couldn't find any documentation for the interfaces or classes being used.
What I am trying to do is to read from an XML file, and add those tags as part of the results that show up in intellisense in the C# code (not in XML).
The part of the R# Plugin Development Guide concerning Code Completion (i.e., IntelliSense) is on our todo list but has not yet been written. When done, it should be available here. While we're working on that, feel free to email me dn at jetbrains dot com, and I'll try to help you out with any queries you might have.
Ok, before I begin I realize that there is a lot of documentation on this subject but I have thus far failed to get even basic colourization working for VS2010.
My goal is to simply get to a point where I can open a document and everything is coloured red, from here I can implement the relevant parsing logic.
Here's what I have tried/found:
1) Downloaded all the relevent SDK's and such- Found the ook sample (http://code.msdn.microsoft.com/ookLanguage) - didn't build, didn't work.
2) Knowing almost nothing about MEF read through "Implementing a Language Service By Using the Managed Package Framework" - http://msdn.microsoft.com/en-us/library/bb166533(v=VS.100).aspx
This was pretty much a copy and paste of all the basic stuff here, and also updating some references which were out of date with the sample see: http://social.msdn.microsoft.com/Forums/en-US/vsx/thread/a310fe67-afd2-4592-b295-3fc86fec7996
Now, I have got to a point where when running the package MEF appears to have hooked up correctly (I know this because with the debugger open I can see that the packages initialize and FDoIdle methods are being hit).
When I open a file of the extension I have registered with the ProvideLanguageExtensionAttribute everything dies as if in an endless loop, yet no debug symbols hit (though they are loaded).
Looking at the ook sample and the MEF examples they seem to be totally different approaches to the same problem. In the ook sample there are notions of Clasifications and Completion controllers which aren't mentioned in the MEF example. Also, they don't seem to create a Package or Language service, so I have no idea how it should work?
With the MEF example, my assumption is that I need to hook into the "IScanner.ScanTokenAndProvideInfoAboutIt" to provide syntax highlighting? Which would be fine if I could ever hit this method.
So my first question I guess is which approach should I be taking here? Or do they both somehow tie together?
My second questions is, where can I find a basic fully working project that implements bog standard basic syntax highlighting and intellisense or VS2010?
Thirdly, in the MEF example when I created a Package there were a bunch of test projects created for me. I appears that the integration tests launch the VS2010 test rig somehow, but the test fails. It would be good to write my service with tests but I have no idea what/how I can test each interaction so any references to testing Language services would be helpful.
Finally, please throw any resource/book links my way that I may find useful.
Cheers, Chris.
N.B. Sorry I realize this is part question part rant, but I have never been so confused.
First, the package example is not using MEF. Essentially everyplace that you mention MEF in your question is not actually MEF, but the managed package framework (MPF), also colloquially called the managed language service (MLS). You'd know if your extension was using MEF by two things: the vsixmanifest lists your assembly as containing a MEF component, and you see [Export] and [Import] attributes in the code.
The easiest way to do this is to use MEF. Since you have the SDK installed, you also have a template for an editor classifier project (under C# (or VB)->Extensibility->Editor classifier in the New Project dialog). You can certainly do this with a language service/colorizer/package, but there will be significantly more code than the equivalent classifier.
The Ook solution is the sample for this and should work; if it doesn't build/work, then can you send me email (noahric at microsoft) with what errors you are seeing so I can email the owner of that sample?
In general, you should also read my answer for the question on "How can I write a plugin for VS2010 using MEF?". That has links to other resources that should help.
Is it possible to generate a set of wiki pages from XML comment file generated by Visual Studio?
I'm talking about something like Sandcastle, but for wiki format instead of compiled CHM.
Edit: I'm using MediaWiki which can import/export articles in XML. So I hope that it is possible to write a transformation converting XML comments to MediaWiki XML.
I'd recommend a bit different solution:
Use Help Server to publish .CHM/.HxS on the web
Use special MediaWiki templates to link reference from Wiki like here.
Use <see href="..."> to link Wiki pages from XML comments
See also: FiXml
This is not exactly what you wanted, but I hope this will be helpful.
If the items mentioned above do not suffice, have you tried to simply build your own XSLT transform into the wiki markup of your choice?
You can write a simple application in .NET (or pick your platform of choice) to transform the doc XML format to wiki XML format. You'd still have to keep the wiki updated with the output files manually.
Is there a utility that will generate html or css for blocks of code (.net c#) when you post it on a website?
I have seen several websites with very nicely formatted code and I dont believe they do this manually.
Google prettify -
http://code.google.com/p/google-code-prettify/
I prefer Syntax Highlighter implementations (I'm using Wordpress plugin implementation for my blog).
Advantages
It is based on JavaScript and does
not care about what you have on the
server.
Posts with this formatting display
properly on different RSS feeds and
can be copied to clipboard.
It is trivial to extend syntax
rules. I'm using that to highlight
custom operators in Boo-based DSL (see sample post)
Multiple languages are supported
out-of-the-box
(source: googlecode.com)
You can get JavaScript syntax-highlighting scripts, such as this one by Dean Edwards.
This is also a jQuery version apparently based on it which looks good.
CopySourceAsHtml is an add-in for Microsoft Visual Studio 2005 that allows you to copy source code, syntax highlighting, and line numbers as HTML.
http://copysourceashtml.codeplex.com
It's highly configurable, and works much better than the download page would make you expect! Don't know if there is something similar for VS 2008
If you don't have the ability to add the google prettifier CSS reference, this would be a better way to go, as what you get is a complete HTML with the required style. I use it all the time on our developers wiki, and loving it.
An even better solution, if you don't want to bother installing anything, is to just use the little web app I wrote called BlogTrog CodeWindow:
http://www.blogtrog.com
It's easy to use. Just paste your code and embed the results.
Is there an easy way to produce MSDN-style documentation from the Visual Studio XML output?
I'm not patient enough to set up a good xslt for it because I know I'm not the first person to cross this bridge.
Also, I tried setting up sandcastle recently, but it really made my eyes cross. Either I was missing something important in the process or it is just way too involved.
I know somebody out there has a really nice dead-simple solution.
I'm reiterating here because I think my formatting made that paragraph non-inviting to read:
I gave sandcastle a try but had a really hard time getting it set up.
What I really have in mind is something much simpler.
That is, unless I just don't understand the sandcastle process. It seemed like an awful lot of extra baggage to me just to produce something nice for the testers to work with.
You're looking for Sandcastle
Project Page: Sandcastle Releases
Blog: Sandcastle Blog
NDoc Code Documentation Generator for .NET used to be the tool of choice, but support has all but stopped.
Have a look at Sandcastle, which does exactly that. It's also one of the more simpler solutions out there, and it's more or less the tool of choice, so in the long run, maybe we could help you to set up Sandcastle if you specify what issues you encountered during setup?
You should also use the Sandcastle Help File Builder. It provides you with a ndoc like GUI for generating help files so you don't have to do anything from a command prompt.
Welcome to the Sandcastle Help File Builder Project
I've just set up Sandcastle again. Try installing it (the May 2008 release) and search for SandcastleGui.exe or something similar (it's in the examples folder or so).
Click Add Assembly and add your Assembly or Assemblies, add any .xml Documentation files (the ones generated by the compiler if you enabled that option) and then Build.
It will take some time, but the result will be worth the effort. It will actually look up stuff from MSDN, so your resulting documentation will also have the Class Inheritance all the way down to System.Object with links to MSDN and stuff.
Sandcastle seems a bit complicated at first, especially when you want to use it in an automated build, but I am absolutely sure it will be worth the effort.
Also have a look at Sandcastle Help File Builder, this is a somewhat more advanced GUI for it.
Follow this simple 5 step article and you are pretty much done. As a bonus you can use H2Viewer to view Html Help 2.x files.
I use NDoc3