NamespaceDoc summary

Jun 30, 2009 at 4:38 PM

Hi,

I have Sandacstle version 1.6 and I cant seem to generate the namespace summary. It shows up as Missing inspite of being in the XML. Is there something that I'm missing?

Thanks

Neha

Coordinator
Jun 30, 2009 at 7:07 PM
Edited Jun 30, 2009 at 7:08 PM

Namespace summaries won't show up unless you enter them with the Namespace Summaries option (the button to the right of the assembly list) or use a NamespaceDoc class to get them in the XML comments file (v1.7 and later only).

Eric

 

Feb 1, 2010 at 7:13 PM

I'm using v1.8.0.3, but I don't see a Namespace Summaries button in the Sandcastle Help File Builder GUI.  Which window is it in?  (I did get the NamespaceDoc class to work, though.)

What am I missing?

-Ken

Coordinator
Feb 2, 2010 at 2:22 AM

Project and namespace summaries are now accessed via the properties in the Comments category.  See the v1.8.0.0 release notes for a complete set of changes to the GUI.  Review the v1.8.0.1 - v.1.8.0.3 for any remaining changes.

Eric

 

Feb 3, 2010 at 3:35 AM

Ah, found it.

Thanks,

Ken

Sep 27, 2010 at 4:21 PM

I added ProjectComment.xml to the Documentation Sources. It contained documentation for the project and namespaces in my project. When I ran the build, it did not do anything with the ProjectComment.xml file and the namespaces ended up showing the warning about a missing description. Am I doing something wrong here? Is there another place to add an .xml document that is not directly associated with an assembly?

I got the idea for this from http://social.msdn.microsoft.com/forums/en-US/devdocs/thread/6766bd99-cd63-41fd-9f03-650ec7eddf3d/.

The ProjectComment.xml looks something like this:

<?xml version="1.0"?>
<doc>
 <members>
  <member name="R:Project">
   <summary>About the project.</summary>
  </member>
  <member name="N:Namespace_1">
   <summary>
    About Namespace_1.
   </summary>
  </member>
  <member name="N:Namespace_2">
   <summary>
    About Namespace_2.
   </summary>
  </member>
 </members>
</doc>

While I realize that I can add the description for each namespace through the SHFB gui, there are a couple of reasons why I don't want to do this.
1. Our projects tend to have large number of namespaces and entering the items through the GUI can be tedious.
2. It's not something I trust the developers to keep up with. It's one more step in their development process that many are loath to maintain. 
I'll have an easier time getting them to maintain the xml file than to fire up the SHFB GUI (as much as I like the tool;).
Richard

 

Coordinator
Sep 28, 2010 at 7:41 PM

I tried a quick test and adding a namespace comments file works as expected.  In the build log, you should see the file listed in the Validating Documentation Sources build step.  Note that the namespace name must match exactly including the "N:" prefix.  Another option that may be more agreeable to your developers is to maintain a NamespaceDoc class within each namespace in their code.  That way, they can keep the comments in the code in the namespace to which it relates rather than in a separate XML file.  See the Using NamespaceDoc Classes help topic for more information.

Eric

 

Sep 28, 2010 at 8:09 PM

I went back in and tried it again. I got the same result. The log did not indicate that the ProjectComment.xml was processed either.

So I opened up the shfbproj file with an XML editor.  I screwed myself on this one. I had created 2 DocumentationSources elements with conditions that allowed me to do a desktop build and a Team build from the same project.

I had used the SHFB GUI to add the ProjectComment.xml file. It shows up in the Documentation Sources panel. When I saved the project prior to the build, it put it in the section that would be selected if it were a team build. Since I was running it from the desktop it never picked up the ProjectComment.xml. It built just like the project description was written.

Once again, you can chalk it up to user error. My apologies for wasting your time.

Richard