XML Elements not found by SHFB

Topics: User Forum
Oct 25, 2011 at 8:40 PM

VS2008 Pro

With a setup close to the default settings, I generate a Help file using the Help 1 method. So far so good. However, some <summary> elements are shown as missing in both the Lastbuild.log and in the generated help. I noticed this first with a few of my Class topics. Looking at the XML that was used by SHFB - according to the log - the topics are present and are as I expected to find them. The XML entry is:

</member><member name="T:ExpTreeLib.CPidl">
 <Summary>cPidl class contains a Byte() representation of a PIDL and
 certain Methods and Properties for comparing one cPidl to another</Summary>

The LastBuild.Log reports:

Info: BuildAssembler: Building topic T:ExpTreeLib.CPidl
Warn: ShowMissingComponent: Missing <summary> documentation for T:ExpTreeLib.CPidl

Further investigation showed that none of the elements of that Class are included in the Help, and do produce warnings in the Log, even though present in the XML. Other Classes work as expected, but some other Classes, present in the XML, are not found.

I need some help in trying to figure out what is wrong here - anything to look for?

Jim Parsells

Oct 25, 2011 at 9:55 PM

More info:
The Class cited in my last post had XML comments on some, but not all Properties and Methods. None of these comments showed up in the Help file and all were cited as Missing in the Log. The constructor had no comment, so I added a <summary> and <remarks>. That one <summary> and <remarks> showed up in the Help file??? None of the others did.

Sooo --- I added <summary> and <remarks> to a couple of other previously undocumented Methods. They now show up in the Help file.

I removed and replaced from scratch the comments on a previously documented Property. Now it shows up.

I modified the comments on a previously documented method by changing the wording a bit. It still does not show up.

When the XML is viewed in Notepad++ there is no obvious difference between comments that show up and those that do not.

Oct 26, 2011 at 12:42 AM

Well, I knew it had to be something I did. I just did not know when I did it.
This is a very old project. It was originally written in VS2002 or VS2003. At that time, XML Comments were not available in VB.Net and were brand new in C#. Some number of the comments written in the early days used a pseudo XML commenting language. To wit --- it used <Summary>....</Summary> rather than the correct <summary>...</summary>. Subsequent updates to the comments only updated the text.

As it turns out, the VB.IDE doesn't care about casing. However, SHFB does. VS was perfectly happy with <Summary> and gleefully put it in the XML. One global Find and Replace fixed my problems.

Thanks anyhow,