Large Number of Namespaces causing issues

Topics: Developer Forum
Feb 10, 2011 at 3:23 PM

We are using Sandcastle Helpfile Builder and have issues when attempting to generate documentation for our codebase, specifically we see missing documentation for Namespaces, e.g. [Missing <summary> documentation for "N:Numero.SmartAgent.ResourceManager"]), Classes, Properties and Methods, if we create a project creating documentation for a subset of the assemblies using the same XML files everything seems to work fine and the namespace and class summaries are generated.

Are there any know limitations on the number of namspaces that can be documented in a single project?

Feb 10, 2011 at 6:29 PM

There are no issues that I'm aware of.  Check the NamespaceSummaries property in the SHFB project to be sure that the comments are there.  If you are using NamespaceDoc classes within the code, make sure they created correctly, are in the correct namespace, and have the right comments.  If using NamespaceDoc classes, check the XML comments file to be sure that they are there after the build and that you are using the correct configuration in SHFB (Debug or Release) when building the help file.



Feb 11, 2011 at 8:08 AM

I have checked the XML comments file and the namespace comments are definitely there, this issue occurs for both Debug and Release configuration. As I stated earlier if I clone the project and remove most of the documentation sources (going from 29 to 2) then the namespace documentation is generated.


Feb 13, 2011 at 7:24 PM

You might check the build log to be sure that it is actually picking up the correct XML comments files.  You can also check the output in the log from the BuildAssembler step to see if it's scanning the XML comments files and if there are any issues with duplicates that may be causing problems.  Set the CleanIntermediates project property to false and check the copies of the XML comments files in the working folder to be sure the comments are present there as well.  Other than that, I'm not aware of any problems that would cause the comments to not get picked up besides the IDs not matching between the comments members and the reflection information.  That can happen for some IDs containing generics but it won't affect namespace IDs.



Feb 14, 2011 at 12:33 PM

Doh... so after checking the build log in more detail I found that while cloning the project I corrected a path error caused by someonelse refactoring the build environment but didn't notice that not only was that wrong in the main file but that the main project included a couple of documentation sources that got deleted in the same refactor.  (The checkin comment was something along the lines of "why are we copying these XML files around, they're not used")

So not an issue - user error.