Commenting Generated Code

Sep 25, 2008 at 8:15 PM
I am working with the Web Service Software Factory and I would like to add comments to the default <summary> comment on classes and add comments to the methods and properties created by the code generation process.

What would be the recommended guidance for achieving this? 

Shane
Editor
Sep 25, 2008 at 8:38 PM

For tool-generated code, the most likely approach would be to maintain a separate XML comments file that you could add to your documentation project if you are using the Sandcastle Help File Builder or DocProject or to the sandcastle.config file if you are using your own build scripts.  That way, you can regenerate the code at will without losing the comments.

If you're managing the sandcastle.config file yourself, add your extra comments file after all the others in the CopyFromIndexComponent component configuration that is preceded by the "Copy in comments" comment.  The Sandcastle Help File Builder manages this automatically.  I'm not sure about DocProject.  With your comments file listed last, your comments override any matching comments found earlier in the preceding files and they will appear in the help file.

Eric

Sep 25, 2008 at 9:09 PM
Hi Shane,

I agree with Eric that adding external XML documentation to the help build process is the most appropriate solution.

I'd just like to add that DocProject also allows you to configure the CopyFromIndexComponent to include external XML documentation files.  The recommend approach though is to use the Topic Editor to create external XML documentation or you can create your own XML documentation file and drop it in the Comments folder.  DocProject will merge it with the compiler-generated documentation automatically during help builds.  (Just make sure you use the same file name as the compiler-generated file if you're not using the Topic Editor.)

- Dave
Oct 1, 2008 at 4:10 PM
Thanks for the info.  One more question.  Does this mean that I should turn off the comment genration in the VS project?  I like the idea of having both files that get merged together, especially with the option that shows missing documentation.  That way I get to review any features which I have not documented via the external doc file.

Shane
Oct 1, 2008 at 5:08 PM
Hi Shane,

DocProject automatically merges your external XML documentation file with the file generated by the compiler.  You have the option of specifying whether external comments overwrite existing source code comments or visa-versa.

There is no missing documentation comments feature in DocProject.  Instead, simply refer to the compiler warnings that are generated when XML documentation is enabled for the project.

- Dave
Editor
Oct 1, 2008 at 11:13 PM
Leave the comments option enabled in the VS project.  In the SHFB project, just add the extra comments file to the Assemblies to Document list and set the CommentsOnly property on it to True.  It will then pick up the assembly comments file and the extra comments file and include the combined comments from both files when generating the topics.  The ShowMissingComponent will add "missing" notes to any missing elements based on the project's "Show Missing Tags" category property settings.

Eric
Feb 25, 2010 at 9:32 PM

This sounds like the same problem I'm trying to solve.  I want to leave the <summary> and <param> elements in the .cs file, and place the <remarks> and <examples> elements into a seperate XML file.  This way I can add/update examples to the documentation without having to recompile the assembly.  I cannot find how to set the CommentsOnly property within SHFB 1.8.0.3.  I've added my assembly.dll, assembly.xml (compiler generated), and assemblyextra.xml to "Documentation Sources" in the "Project Explorer", but assembly.xml and assemblyextra.xml are not being merged together.  I'm getting a last one wins result.

Is this scenario possible within SHFB and how do I set the CommentsOnly property?

Mike

Editor
Feb 26, 2010 at 9:06 PM

The CommentsOnly property doesn't exist in v1.8.0.3.  You just add the extra comments files as documentation sources as you have done.  However, your problem is that the Sandcastle build component does not merge comments for member elements that are duplicated in multiple comments files.  It's behavior of "last one seen wins" is the way it works.  In order to provide that functionality, you would need to write a plug-in for SHFB that loads the XML comments files and merges the duplicate members into one entry containing the unique comment elements from each and deletes the member from one of the files.

Eric