I have a class (not a structure) that contains public constants.  I have documented them using the XML documentation tags available to them (summary, remarks).  Comment Editor respects them and shows them.  But, once the help is compiled, the constants are missing from the documentation altogether (no topic pages for them, no entries in the member summary tables, nothing).  Worse, their documentation is randomly concatenated to unrelated members' documentation.

For example, I have a constant field called TestField, which has summary and remarks defined for it.  I also have a property called TestProperty, which also has summary and remarks (along with other documentation parts) defined for it.  Both have correct XML comment tags in the source code, and the comment editor works as expected for both.  I compile.  The documentation for the TestField is missing in the compiled help (as if the field weren't there.  But TestProperty has a summary that has its own plus the summary of TestField concatenated, and remarks that are its own plus the remarks of TestField concatenated.  If there are multiple fields, multiple fields' documentation may be concatenated into the documentation of a single, unrelated member.  Which member gets the field's documentation is unpredictable (may be a property, may be an event).

Note that this error does not occur with structures.  While it is typically considered bad practice for many reasons to use raw public fields rather than properties in exposed types, this error occurs for constants too, and public constants containing special values for end developer use are quite normal (i.e. a math component that has constants for mathematical constants).  This makes this a serious issue.

I am using the latest evaluation of Document!X (as of 9/25/2009), Visual Studio 2008 SP1 (VB.NET), and generating Help 2.0 documentation for plug-into Visual Studio 2008 documentation.  I am using Windows XP (latest service packs) and IE 8.  If it would help someone, I could send my whole project and the resulting documentation (it is only a test project for evaluating Document!X).

It would be great if you could send through your sample project to support@innovasys.com so that we can investigate this one. My suggestion would be to document your compiled assembly rather than from the VB.NET source code - the end result is the same and my hunch would be that if this is a bug it's related to documenting from the VB.NET source instead of the compiled assembly.

Documenting the compiled assembly fixed this problem - but it has another one:

The assemblyname.xml intellisense comment file generated by Document!X is not correct.  It identifies operators as properties, uses wrong syntax for identifying delegates defined in classes, and the syntax for generic methods is wrong (based on a comparison with the syntax generated by Visual Studio compiler).  The result of this is that the intellisense shows information for a delegate within the class as the information for the class, no information for operators, and no information for generic methods.  The intellisense comment file generated by Visual Studio compiler does not have these problems.  This is an issue because if you document the compiled assembly instead of the source code, you are relying on Document!X to generate the proper intellisense comment file based on the documentation of the already compiled assembly, rather than the other way around.

I have e-mailed you another sample project (it is the same one as the last one I sent you, but the comments are stripped out of the source code, and are in the Document!X content file instead, based on documenting the compiled assembly.  In this sample, the TestMethod method of the generic class has no intellisense, and neither do the operators.  Both classes have the intellisense for their contained delegate, rather than their own summary and remarks.

We will get back to you via the support channel shortly on this issue, but one thing that might be worth mentioning in the meantime is that you documenting from the assembly doesn't mean that Document! X can't use the source comments - so long as you configure your VB.NET project to generate an Xml documentation file then Document! X will use that when building from the assembly. The situation in which you need to have Document! X generate the intellisense Xml documentation file is if you are creating your summary content in a Content File rather than source Xml comments.

The combination of using source code comments and generating the compiled help from the assembly, and using the assemblyname.xml file from the Visual Studio compiler fixed the problems.  This workaround would be acceptable.  Thank you very much for your investigation and help.