0

Fields and Constants in Classes corrupt other members documentation

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).

4 comments

Please sign in to leave a comment.