Summary not showing up in Documentation.

Topics: User Forum
Jun 17, 2010 at 10:22 PM

Hey Guys,

I am using Sandcastle help file builder version 1.8.0.3.  When generating a website of documentation, some of the class summaries are not showing up.  Any ideas what could me causing this?

Thanks,

Poohshoes

Coordinator
Jun 18, 2010 at 7:07 PM

Check the XML comments files being used by the SHFB project.  Are the expected comments in there?  If not, it could be that you just need to rebuild the web project to recreate the comments file.  You might check the build log to be sure that it's picking up the correct comments file too.

Eric

 

Jun 18, 2010 at 10:09 PM

Thanks for the reply.  It seems that I was using the .xml in the Debug folder when I was compiling to the Release folder, thanks for your help.

Jun 25, 2010 at 10:55 PM

Eric,

I am having the same probelm. I have rebuilt the page, checked the XML output(my comments are there)  and made sure i am not in the debug folder. My summary comments are still not there. It is for a website and I believe i have done everything correctly. One question for clarification. Do I need both the .dll and .xml files as documentation sources for my sandcastle project? Even my boss (an actual developer) can't figure it our. Please help. As always I appreciate it.

Sharon the Perplexed Tech Writer Who May be In Over Her Head

Jun 25, 2010 at 10:57 PM

In reference to my question currently both .dll and .xml files are included in the project currently.

Coordinator
Jun 28, 2010 at 2:01 AM
Edited Jun 28, 2010 at 2:02 AM

Check the build log to see which assembly and which comments file are being used.  Check that comments file to see if the members you are expecting to see comments for are in it.  Also, is it that the comments are not there or that the member itself is not there.  If the member itself is not there, is it public?  If not public, you won't see it unless you set the DocumentPrivates and DocumentInternals properties to true.

Eric

 

Jun 28, 2010 at 5:09 PM

As far as I can tell both are there. Here is the line from the xml comments file.

  <member name="M:Common.ConnectionString"> 
  <summary>This class returns the string that used in code to connect to
the database. This is so the user doesn't have to query the web.config for the string.</summary>
  <returns>The connection string from web.config</returns>
  </member>

 

I don't even see this page in the help that compiles. Thanks as always.

Sharon

Coordinator
Jun 28, 2010 at 7:11 PM

Is the member public?  If not, it won't show up unless you set the properties as I mentioned above.  Also, is the XML comments file generated by the compiler or is it something that was written by hand?  If by hand, perhaps it's not valid in some way.  Apart from that, I'm out of ideas.

Eric

 

Jun 28, 2010 at 7:34 PM

I changed the properties as you said. The comments are added by hand, any ideas on why they might not be valid?

Coordinator
Jun 28, 2010 at 7:40 PM

If you're authoring the XML comments file by hand, it's most likely failing because the member ID does not match up with the actual ID generated by the MRefBuilder tool.  For example, in your example above, is that a method or a property?  If it's a method, that's okay as long as there are no parameters.  If it's a property, it won't work because the prefix needs to be "P:" for properties.

Eric

 

Jun 28, 2010 at 9:30 PM

The only things I am writing by hand are the summaries. The rest of the project is already created. Some of the pages are generating in sandcastle but not others. The page where the member I showed you appears is not showing in the html help at all. That is the only page where I have added summaries.

What should we do if our members do have parameters? Is there a way around it?

Coordinator
Jun 29, 2010 at 2:06 AM

If your methods don't have parameters, your example would be fine as it is.  If it had parameters, you'd need to add them to the member ID.  As as said though, the one above looks like a property so the prefix is wrong and it won't work.  If you can't figure the ID out, set the SHFB project's CleanIntermediates property to False and, after the build, open the reflection.xml file and find the member.  That' will be the syntax you need to use.  That's probably more info that you want to deal with though.

Eric

 

Jun 29, 2010 at 3:28 PM

I will pass it on to my boss and see what he wants to do. You have been more than helpful. Thank you so much! It's so rare for me to actually get help on any forum. I really appreciate the fact that you take time to respond. : )