I had read early on that one can document C# code with XML, and today since I was reviewing all my code and comments, thought it would be a good time to try this myself. You just use three slashes instead of two, and insert XML tags around your comments. Then Visual Studio can generate the XML file when you Build, and you can display the XML in a nice HTML page if you use an XSLT stylesheet. And if you want your nice HTML page to look like MSDN, you might check out Sandcastle, an add-in for VS to generate such pages.
Hereare some of the sites that seemed most helpful:
- XML Documentation in C# (Microsoft)
- Simple XSLT stylesheet for your documentation from Code Project
- XSLT Tutorial from W3C Schools
Before I got too far along, I realized I was missing some of the 'commands' in VS necessary to generate the XML. This is because I've got a Web Site instead of a Web Application (see Birth of ListMaker post). Which raised the question, just what is a 'Web Application' to VS? This is one of those basic questions that is hard to find information about since most folks have moved on - but, Scott Gu has an excellent introductory tutorial: Visual Studio 2005 Web Application Project Option. Also a nifty comparison chart and additional details on MSDN.
And here is one way to generate the XML doc for a .cs if you don't use the Web Application template:
>csc common.cs /doc:mydoc.xml
but, this just does the one file. In forums.asp.net, I found sample code that will do it for all the files and do it without opening the command line ... http://forums.asp.net/t/843207.aspx ...
Also, for future reference, here are other compiler options: http://msdn2.microsoft.com/en-us/library/ms379563(vs.80).aspx
1 comment:
Post a Comment