Fresno Bob

I am using the website project for my site. How do I compile and output an
XML comments file. I have tried to publish the file to a folder C:/sand and
specify a compiler option in my web.config
compilerOptions="/doc:c:\sand\app_code.xml" /> but this not does work:

Should this work or am I going in the wrong direction

I want to use sandcastle for my first .net project but I have done it as a
website project. Can anyone point me in the right direction on outputing the
xml comments. Regards, Chris.



Re: Developer Documentation and Help System Getting website project to output XML Comments

EWoodruff

See http://www.codeplex.com/DocProject/Wiki/View.aspx title=How%20To%20Build%20Help%20For%20a%20Web%20Site%20Project for some information that may help. The first section should help you set up the project correctly regardless of the tool or script you are using to build the help file.

Eric





Re: Developer Documentation and Help System Getting website project to output XML Comments

Fresno Bob

Hi I have got it outputting an XML file but the comments in my code aren't there. As I am new to this I suspect I am doing something stupid:

Here is my class in my App_code folder

Public Class sandcastle2

''' <summary>This is a test function called Test TestSandcastle2</summary>

''' <remarks>Updates the record</remarks>

''' <paramref name="id"/>

''' <param name="SandID">The ID of the record to update.</param>

''' <returns>Returns a value of 2</returns>

Public Function TestSandcastle2(ByVal SandID As Integer) As Integer

Return 2

End Function

End Class

Here is the web config

<compiler language="vb;visualbasic" extension=".vb" compilerOptions="/docBig Smileebug/bin/Sandcastle_deploy.xml"

type="Microsoft.VisualBasic.VBCodeProvider, System, Version=1.0.5000.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"/>

Here is the outputted XML. What I am doing wrong Smile

< xml version="1.0" >
- <doc>
- <assembly>
<name>App_Web_lnrro2uv</name>
</assembly>
<members />
</doc>




Re: Developer Documentation and Help System Getting website project to output XML Comments

Dave Sexton

Hi,

The instructions apply to the generation of xml documentation for .aspx files only, not general source code files found in the App_Code folder. To build documentation for source code files I highly recommend moving them to a Class Library project.

Although, if you absolutely must keep them in your web site project then there is a somewhat convoluted way of generating xml documentation files from code comments in App_Code files, although it requires a few more manual steps and only works with VB.NET, not C#.

Generate code documentation xml for ASP.NET 2.0 website

http://www.velocityreviews.com/forums/t119872-generate-code-documentation-xml-for-aspnet-20-website.html

I successfully tested this solution myself with VB.NET. I'll update the DocProject instructions with this information soon.

Basically, you need to use the /doc+ switch instead of specifying a file name. Visual Studio runs the compiler separately for code files and .aspx pages, so if you specify the name of the documentation file it will be replaced with each compilation. The VB.NET compiler's /doc+ switch will create multiple xml documentation files in the .NET temporary directory, commonly found at C:\Windows\Microsoft.NET\Framework\v2.0.50727\Temporary ASP.NET Files. In this temporary directory, find the folder with your web site project's name and somewhere in one of the temporary sub folders you'll find multiple xml files that contain the code comments from your App_Code files after you build the web site project.

Depending upon how you configured Sandcastle you may be able to use the .xml files as is. For DocProject, open your Build Process Component and in the BuildStarting method you can add code that will locate and copy these files into DocProject's working directory so that Sandcastle will see them.

HTH

- Dave






Re: Developer Documentation and Help System Getting website project to output XML Comments

Dave Sexton

I updated the documentation but I chose not to include information about /doc+ for VB.NET projects:

How To Build Help For a Web Site Project

http://www.codeplex.com/DocProject/Wiki/View.aspx title=How+To+Build+Help+For+a+Web+Site+Project

There are other benefits to using a Class Library Project over the App_Code folder other than this, but I couldn't think of any downsides so I'm recommending this approach only.

Thanks for bringing this issue to my attention.

- Dave






Re: Developer Documentation and Help System Getting website project to output XML Comments

Fresno Bob

Thanks for the help but I am getting a little confused - which is due to being new to .net: Are you saying

The web deployment approach discussed does the output for the aspx pages.

If I want to output the XML comments for e.g. my business objects I need to stick them in a project and compile it separately.

Currently all my business objects are in the App_Code folder and there are about 50 vb files. Can I put them all as a group in a class library project and link to them in my web site project. I am from an ASP web design background so any links would be apprieciated if it is a bit broad to explain in a single post.

It's just that having them in the app_code folder is a bit closer to ASP where any of the team can just look at the code. Ideally I would like that simplicity especially for the rest of the team who have even less experience than me.

Regards, Chris.





Re: Developer Documentation and Help System Getting website project to output XML Comments

Fresno Bob

One slightly separate issue. I have got my Sandcastle project working from a web application project but my summary and remarks aren't appearing anywhere. Regards, Chris.





Re: Developer Documentation and Help System Getting website project to output XML Comments

Dave Sexton

Hi Chris,

Unlike Web Application projects, Web Site projects were designed to build their assemblies at runtime upon the first request to the site. When you build your web site project Visual Studio runs the VB.NET compiler to generate an assembly to ensure that the project can be built, however it doesn't copy the assembly into the project's bin directory.

Using the web.config file as in my example, you can tell the VB.NET compiler to output xml documentation files as well. By providing a hard-coded file name, as in my example, the VB.NET compiler can only produce one xml documentation file, no matter how many assemblies it creates. The last file generated will overwrite the previous one since they have the same name. In VB.NET, the /doc+ switch tells the compiler to create the xml documentation file name itself, and if its unique it will not be replaced.

The VB.NET compiler generates a single xml documentation file that contains all of the xml comments in your .aspx code behind files. This file alone is imported by the Web Deployment project.

The Web Deployment project is used to copy the assembly output and optional xml documentation file into its bin directory from the ASP.NET temporary directory. However, it's not designed to copy all .xml files so if you use the /doc+ switch you must get them yourself by examining the contents of the ASP.NET temporary directory after you build your Web Site project.

If you create a business object library based on a Class Library project template then your business objects will be compiled into a separate assembly. Class Library projects have an option to produce a single xml documentation file for all of the code in the project. The file is created in the project's bin directory, along with the assembly. You can then use these files with Sandcastle.

To create a Class Library project try these instructions:

Modeling a Real-World Object: Creating Your First Class

http://msdn2.microsoft.com/en-us/library/xhfeshak(VS.80).aspx

Since you already have created the source code files you simply need to move them into the new project after it's created.

You can reference the class library project from your Web Site project using a project reference. Right-mouse click your Web Site project in Solution Explorer and select Add Reference. On the Projects tab, select your Class Library project from the list.

Once referenced, the types defined in your Class Library project can be used in your Web Site project by simply importing the appropriate namespace at the top of your code behind files.

Having a class library for your business objects also allows you to use them for other projects. For example, if you need to make a Web Service project or a WinForms project for the same solution then you can reuse the business logic by simply referencing your Class Library project in your new projects as you did with your Web Site project.

- Dave






Re: Developer Documentation and Help System Getting website project to output XML Comments

Dave Sexton

Hi Chris,

Are you using a community tool to automate Sandcastle or batch files

I suspect that you're using batch files but haven't updated the sandcastle.config file to look for your xml documentation files. By default, it's hard-coded to look for a single file named, comments.xml. See my response in this thread.

- Dave






Re: Developer Documentation and Help System Getting website project to output XML Comments

Peter Macej

As an alternative to Sandcastle, you can try our VSdocman. You can generate XML file (or directly resulting documentation) for your web site including App_Code folder with single mouse click.