When you compile with csc.exe /doc command line argument, it will read your XML comments intended for documentation and build your XML file. From within VS.NET 2005 if you access your project properties and choose the Build tab, there is a checkbox "XML Documentation
File" that does the same thing as the command line. Once you have this doc file, you might then want to look at
NDoc to then generate a .chm file from the XML doc file. If you're using VB.NET, I think they added in the same ability in 2.0. -Brock
Could someone clarify how to get VS 2005 to output the XML documentation file for a web project?
The "build tab" discussed in the previous post only seems to have the described XML documentation options for non-web projects. How do we output the XML docs for a web project though?
Has anyone found a solution for this? I'm out of ideas and I've spent quite a lot of time digging through the web, MSDN, forums, etc...
There must be a way to generate the XML file for comment documentation in a C# ASP.NET 2.0 web app isn't there?
What disturbs me is that I'm seeing almost no inquiry into this on the web. That either means it is stupid simple and I'm just overlooking something... or this feature is tragically under-utilized .
Are you talking about generating docs for the code in your ASPX classes? If so, I don't understand how you'll be using this documentation... If that's not it, what exactly are you looking for?
I can tell you why you're not getting what you're looking for -- it's primarily because VS.NET is not doing the compilation of the ASPX pages. ASP.NET is doing the compilation. Now you can alter the command line passed to the C# or VB.NET compile by adding
the /compilerOptions to your web.config in the <compilation>/<compilers>/<compiler> element. Maybe this is what you're looking for?
That is the best I've seen so far. Thanks for the pointer -- but that doesn't seem to do the trick. See, I can put in the compiler option for /doc:c:\somepath\somefile.xml, and it indeed generates the documentation. But it appears that the vs 2005 build
of a web site does it folder by folder so the documentation file keeps getting overwritten as the build progresses.
At least I "think" that's what happens. When I add the <compiler> element to web.config specifying the c# compiler and options, it goes through some of the build until I get an error "Build (web): The application domain in which
the thread was running has been unloaded." This will happen at a random point during compilation, not in the same part of the build. The generated XML file will only contain information from the classes being compiled just before the error. So
I'm assuming that the same xml file is being written for each folder VS 2005 builds, and at some point the compiler trips over itself and breaks trying to read a file before another handle has been released. That's guess work, but seems to be about right.
Is there a way to put in a variable to the /doc:filename compiler option so that it would name the file based on the folder or input file name? I didn't see anything like that in the documentation for the C# compiler.
What I'm mostly looking for is generated XML documentation on stuff in the App_Code folder.
I'm not as concerned with the code-behind and inline code though I often do put in XML comments for them.
I'm just confused. XML comment documentation was a great feature. It rocked! And MS extended it to VB for the 2005 release. Then they disable all support for it in web apps? That just doesn't make sense!
Anyway, if you have any more suggestions, I'm still needing a solution :)
I got an email from Doug Stone with a brilliant suggestion that fixes the major issue.
All you have to do is put web.config files into all the individual folders. In each web.config file you put in a compilers section with the C# or VB compiler element configured to output the documentation xml file (using a unique path and/or name for each
file folder).
Alternatly, you can combine all this into the main web.config file in the root using <location> elements.
This is a workable solution, if still cumbersome and awkward. I'd like to see a future version of visual studio support xml documentation for web projects directly so we can get around having to manually configure compilers all over the place, and most importantly
so that we can use a relative path as the drop location for the XML file (using the compiler element you have to use a fixed path, so it doesn't work out so well in team environemnts where you build the project on many different individual developer systems.
Is it just me or is XML Comment funcationality going backwards as Visual Studio progresses? In 2002 we had XML file build output and a doc web site generation tool. In 2003 we only had XML file build output. In 2005 we don't have either (in web apps and
win apps still only have XML file build output). Just a price of progress or a trend of degression?
Actually, the problem is getting the XML file that NDoc needs in order to build the documentation. NDoc and similar tools are exactly what I want to use... but VS 2005 and ASP.NET 2.0 make gerating the XML file from the code comments very difficult for web
apps.
tommyo
Member
195 Points
39 Posts
Xml documentation?
Mar 01, 2005 11:31 AM|LINK
BrockAllen
All-Star
27532 Points
4906 Posts
MVP
Re: Xml documentation?
Mar 02, 2005 04:06 PM|LINK
DevelopMentor | http://www.develop.com
thinktecture | http://www.thinktecture.com/
Redd
Contributor
5271 Points
1061 Posts
Re: Xml documentation?
Jun 21, 2005 04:12 PM|LINK
The "build tab" discussed in the previous post only seems to have the described XML documentation options for non-web projects. How do we output the XML docs for a web project though?
http://www.reddnet.net
Haplo
Member
35 Points
7 Posts
Re: Xml documentation?
Nov 23, 2005 05:43 PM|LINK
Redd
Contributor
5271 Points
1061 Posts
Re: Xml documentation?
Dec 06, 2005 09:05 PM|LINK
Has anyone found a solution for this? I'm out of ideas and I've spent quite a lot of time digging through the web, MSDN, forums, etc...
There must be a way to generate the XML file for comment documentation in a C# ASP.NET 2.0 web app isn't there?
What disturbs me is that I'm seeing almost no inquiry into this on the web. That either means it is stupid simple and I'm just overlooking something... or this feature is tragically under-utilized .
http://www.reddnet.net
BrockAllen
All-Star
27532 Points
4906 Posts
MVP
Re: Xml documentation?
Dec 06, 2005 10:27 PM|LINK
Are you talking about generating docs for the code in your ASPX classes? If so, I don't understand how you'll be using this documentation... If that's not it, what exactly are you looking for?
I can tell you why you're not getting what you're looking for -- it's primarily because VS.NET is not doing the compilation of the ASPX pages. ASP.NET is doing the compilation. Now you can alter the command line passed to the C# or VB.NET compile by adding the /compilerOptions to your web.config in the <compilation>/<compilers>/<compiler> element. Maybe this is what you're looking for?
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpgenref/html/gngrfcompiler.asp?frame=true
-Brock
DevelopMentor | http://www.develop.com
thinktecture | http://www.thinktecture.com/
Redd
Contributor
5271 Points
1061 Posts
Re: Xml documentation?
Dec 07, 2005 03:10 PM|LINK
That is the best I've seen so far. Thanks for the pointer -- but that doesn't seem to do the trick. See, I can put in the compiler option for /doc:c:\somepath\somefile.xml, and it indeed generates the documentation. But it appears that the vs 2005 build of a web site does it folder by folder so the documentation file keeps getting overwritten as the build progresses.
At least I "think" that's what happens. When I add the <compiler> element to web.config specifying the c# compiler and options, it goes through some of the build until I get an error "Build (web): The application domain in which the thread was running has been unloaded." This will happen at a random point during compilation, not in the same part of the build. The generated XML file will only contain information from the classes being compiled just before the error. So I'm assuming that the same xml file is being written for each folder VS 2005 builds, and at some point the compiler trips over itself and breaks trying to read a file before another handle has been released. That's guess work, but seems to be about right.
Is there a way to put in a variable to the /doc:filename compiler option so that it would name the file based on the folder or input file name? I didn't see anything like that in the documentation for the C# compiler.
What I'm mostly looking for is generated XML documentation on stuff in the App_Code folder.
I'm not as concerned with the code-behind and inline code though I often do put in XML comments for them.
I'm just confused. XML comment documentation was a great feature. It rocked! And MS extended it to VB for the 2005 release. Then they disable all support for it in web apps? That just doesn't make sense!
Anyway, if you have any more suggestions, I'm still needing a solution :)
http://www.reddnet.net
Redd
Contributor
5271 Points
1061 Posts
Re: Xml documentation?
Dec 08, 2005 03:38 PM|LINK
I got an email from Doug Stone with a brilliant suggestion that fixes the major issue.
All you have to do is put web.config files into all the individual folders. In each web.config file you put in a compilers section with the C# or VB compiler element configured to output the documentation xml file (using a unique path and/or name for each file folder).
Alternatly, you can combine all this into the main web.config file in the root using <location> elements.
This is a workable solution, if still cumbersome and awkward. I'd like to see a future version of visual studio support xml documentation for web projects directly so we can get around having to manually configure compilers all over the place, and most importantly so that we can use a relative path as the drop location for the XML file (using the compiler element you have to use a fixed path, so it doesn't work out so well in team environemnts where you build the project on many different individual developer systems.
Is it just me or is XML Comment funcationality going backwards as Visual Studio progresses? In 2002 we had XML file build output and a doc web site generation tool. In 2003 we only had XML file build output. In 2005 we don't have either (in web apps and win apps still only have XML file build output). Just a price of progress or a trend of degression?
http://www.reddnet.net
BoulderBum
Contributor
3019 Points
610 Posts
Re: Xml documentation?
Dec 08, 2005 05:18 PM|LINK
I didn't read all the details of the posts, but in answer to your original question, use NDoc:
http://ndoc.sourceforge.net/
It's freakin sweet.
You can see some more about it here:
http://www.ondotnet.com/pub/a/dotnet/2002/12/09/ndoc.html
Redd
Contributor
5271 Points
1061 Posts
Re: Xml documentation?
Dec 09, 2005 04:56 AM|LINK
Actually, the problem is getting the XML file that NDoc needs in order to build the documentation. NDoc and similar tools are exactly what I want to use... but VS 2005 and ASP.NET 2.0 make gerating the XML file from the code comments very difficult for web apps.
http://www.reddnet.net