XML Documentation in ASP.NET web sites

[gzinger]

Since I never seen the following question answered, I am re-posting it:

Hi

Im using ASP.NET 2 with C# in codebehind files and Visual Studio 2005 Team
Edition.

I have embedded lots of XML Documentation (<summary>,<see>,etc) into my
ASP.NET project in code behind files of ASP pages, user controls and classes
in the App_Code directory. I have added the "/doc" compiler option using the
web.config (see snippet at bottom of post).

When i build my website it seems to only generate the XML documentation for
one file only.
Is there a way to generate all documentation for the web project?

Also if i give the full path to the /doc option i can find the output but if
i just give a file name i dont know where it creates the file.

Has anyone ever had any success with XML documentation of web projects? Let
me
know if there is a work around that im missing on the web.

Thanks
Ben Crinion

<system.codedom>
<compilers>
<compiler
language="c#;cs;csharp"
extension=".cs"
type="Microsoft.CSharp.CSharpCodeProvider"
compilerOptions="/doc:c:\XMLDOCS.xml"
warningLevel="1" />
</compilers>
</system.codedom

--
http://www.zbitinc.com

[Yuan Ren[MSFT]]

Hi Ben,

Thanks for posting!

For the current issue, my understanding is that you want to generate the
XML document for the current ASP.NET application. If I have misunderstood
anything, please feel free to let me know.

Based on my experience, if you want to generate all document for the
current web application, I recommend you use the NDoc tool at the current
stage. Adding the compile option is not appropriated for the large and
formal web project. You can obtain more information about the NDoc tool via
accessing the following link:
http://www.sitepoint.com/print/dot-n...mentation-ndoc

Hope this will be helpful!

Regards,

Yuan Ren
Microsoft Online Community Support
==================================================
When responding to posts, please "Reply to Group" via your newsreader so
that others may learn and benefit from your issue.
==================================================
This posting is provided "AS IS" with no warranties, and confers no rights.

[gzinger]

Dear Yuan Ren,

Thank you for your reply.
However, you missed a small but very crucial detail in my post. I am asking
about ASP.NET 2.0 (not version 1.x). I have been using NDoc in the previous
version of .NET and was very happy with that. Now, with the release of 2.0
and Visual Studio 2005, however, there are two major problems with
documenting Web Projects (Web Sites).
One, of course, is that NDoc does NOT support version 2.0 of .NET and your
input will be greatly appreciated if you could supply a Microsoft’s internal
tool for this. But even before we get to the actual Documentation production
process, we need to be able to materialize the .XML document out of our web
project, and that is not very easy or I don’t know how to do it in the new
environment.
I am looking forward to find out if there are solutions/workarounds to
resolve both of those issues.

--
http://www.zbitinc.com
""Yuan Ren[MSFT]"" wrote:

Hi Ben,

Thanks for posting!

For the current issue, my understanding is that you want to generate the
XML document for the current ASP.NET application. If I have misunderstood
anything, please feel free to let me know.

Based on my experience, if you want to generate all document for the
current web application, I recommend you use the NDoc tool at the current
stage. Adding the compile option is not appropriated for the large and
formal web project. You can obtain more information about the NDoc tool via
accessing the following link:
http://www.sitepoint.com/print/dot-n...mentation-ndoc

Hope this will be helpful!

Regards,

Yuan Ren
Microsoft Online Community Support
==================================================
When responding to posts, please "Reply to Group" via your newsreader so
that others may learn and benefit from your issue.
==================================================
This posting is provided "AS IS" with no warranties, and confers no rights.

[Yuan Ren[MSFT]]

Hi Ben,

Thanks for your reply!

At the current stage, as far as I know, the NDoc tool has supported the
NET 2.0. You can obtain more details via accessing the following link:
http://community.rainbowportal.net/b...g/archive/2006
/03/21/1685.aspx

Actually, most developers use the NDoc tool to generate the documentation
for their .NET application. The article from MSDN and other third party
site also demonstrate how to use the NDoc tool to approach this:
"Generating Documentation for Your Visual Basic .NET Applications":
http://msdn.microsoft.com/library/de...us/dv_vstechar
t/html/vbgeneratingdocs.asp

"Code Documentation in .NET":
http://aspalliance.com/696

I understand the scenario is different from the current issue. However, as
you mentioned, the ASP.NET only generate the single xml file after
compilation. If you want to materialize the XML document file, the NDoc
tool is much appropriated for the current issue. You can also find other
tools to finish the current job such as the DocumentX, HelpStudio and so
on. However, some of these are not free.

Hope this will be helpful!

Regards,

Yuan Ren
Microsoft Online Community Support
==================================================
When responding to posts, please "Reply to Group" via your newsreader so
that others may learn and benefit from your issue.
==================================================
This posting is provided "AS IS" with no warranties, and confers no rights.

[gzinger]

Dear Yuan Ren,

With all the respect, I didn't hear what I needed to hear from you. It seems
that you are answering some other question. Sorry for being so direct, but I
KNOW how to use NDOC - I have used it for many month and loved how it worked
for VS2003 (including the web projects in it). What I am asking you though is
HOW to use it for web projects (in my case web site contaning web services)
in Visual Studio 2005. In particular, I need to know how to produce the .XML
file, that I was able to produce in VS 2003 by simply adding appropriate
compiler option to the project, and I am not able to produce now.
You are telling me to use NDOC, but it requires that .XML file as an INPUT.
And although it could produce the XML as an output too, I still have to
provide the XML input for it because at very least it requires an assembly
(which I don't have either) and the XML with my comments.
--
http://www.zbitinc.com
""Yuan Ren[MSFT]"" wrote:

Hi Ben,

Thanks for your reply!

At the current stage, as far as I know, the NDoc tool has supported the
.NET 2.0. You can obtain more details via accessing the following link:
http://community.rainbowportal.net/b...g/archive/2006
/03/21/1685.aspx

Actually, most developers use the NDoc tool to generate the documentation
for their .NET application. The article from MSDN and other third party
site also demonstrate how to use the NDoc tool to approach this:
"Generating Documentation for Your Visual Basic .NET Applications":
http://msdn.microsoft.com/library/de...us/dv_vstechar
t/html/vbgeneratingdocs.asp

"Code Documentation in .NET":
http://aspalliance.com/696

I understand the scenario is different from the current issue. However, as
you mentioned, the ASP.NET only generate the single xml file after
compilation. If you want to materialize the XML document file, the NDoc
tool is much appropriated for the current issue. You can also find other
tools to finish the current job such as the DocumentX, HelpStudio and so
on. However, some of these are not free.

Hope this will be helpful!

Regards,

Yuan Ren
Microsoft Online Community Support
==================================================
When responding to posts, please "Reply to Group" via your newsreader so
that others may learn and benefit from your issue.
==================================================
This posting is provided "AS IS" with no warranties, and confers no rights.

[Yuan Ren[MSFT]]

Hi Ben,

Thanks for your reply!

Sorry for misunderstanding!

I think I have known your concern is that generating XML document in
ASP.NET v2.0. I performed the testing and find the issue same with you.
I'll contact our dev team ASAP for the current issue. Thanks for your
patience!

Regards,

Microsoft Online Community Support
==================================================
When responding to posts, please "Reply to Group" via your newsreader so
that others may learn and benefit from your issue.
==================================================
This posting is provided "AS IS" with no warranties, and confers no rights.

[gzinger]

Ok Thanks.
Please keep me posted.

--
http://www.zbitinc.com
""Yuan Ren[MSFT]"" wrote:

Hi Ben,

Thanks for your reply!

Sorry for misunderstanding!

I think I have known your concern is that generating XML document in
ASP.NET v2.0. I performed the testing and find the issue same with you.
I'll contact our dev team ASAP for the current issue. Thanks for your
patience!

Regards,

Microsoft Online Community Support
==================================================
When responding to posts, please "Reply to Group" via your newsreader so
that others may learn and benefit from your issue.
==================================================
This posting is provided "AS IS" with no warranties, and confers no rights.

[Yuan Ren[MSFT]]

Hi Ben,

Thanks for your patience!

One of our engineers also recommends using the NDoc tool. However, I know
your concern is generating XML document but not generating formal or
end-user documentation. Could you please tell me whether my understanding
is correct?

However, I still report the issue to our dev team again. I'll rely you ASAP
when I get some results or workarounds. Thanks for your waiting!

Regards,

Yuan Ren
Microsoft Online Community Support
==================================================
When responding to posts, please "Reply to Group" via your newsreader so
that others may learn and benefit from your issue.
==================================================
This posting is provided "AS IS" with no warranties, and confers no rights.

[Yuan Ren[MSFT]]

Hi Ben,

Thanks for your patience!

There are two ways to approach the current issue:

1) Place the class files you want to get XML documents generated for in a
"Class Library" project and then reference that project from you website.

2) The second option, which might be a better option if you want to
generate XML documentation for code-behind files for pages, in addition to
classes, is to use the Web Application Project instead of a Website
project. Web Application projects is available from
http://www.asp.net/default.aspx?tabindex=5&tabid=41. The current build
that is available is still a preview; however we are releasing an RC
version of the Web Application projects in the coming week.

Regards,

Yuan Ren
Microsoft Online Community Support
==================================================
When responding to posts, please "Reply to Group" via your newsreader so
that others may learn and benefit from your issue.
==================================================
This posting is provided "AS IS" with no warranties, and confers no rights.

[mrodenhauser]

Exellent response...I've been hunting for the same solution. Thank you
Yuan

[Berehm]

Thanks for this post.

However, I was wondering if there is something analogous to the "Web
Application Project" VS add-in for Web-services.

By analogous I mean:

1. All the source files in a Web-services project is compiled into a
single assembly, perhaps with the exceptions of the .asmx file

2. Property pages for the project in VS display all the tabs that are
available in other kinds of projects - i.e., for example, ability to
specify pre and post build events, the XML documentation file etc.

I really appreciate any help.

Cheers,
Adrigo