Question about issue between Sandcastle and Code analysis

Dec 3, 2008 at 6:40 PM
Hello All,

We are running into the following issue when using Sandcastle and code analysis together:

As part of the sandcastle documentation generation, a NamespaceDoc class is added to each namespace in the assembly.  The summary xml comment tag on each NamespaceDoc class is then used to add info about the corresponding namespace.  E.g.:

 

namespace APISoftware.Navigator.Constants

{

    /// <summary>Contains items that are constant throughout the application.  Some constants, like FieldValueList constants are very important to the system and are contained here. </summary>

    internal class NamespaceDoc{}

}

 

FxCop then gives a AvoidUninstantiatedInternalClasses warning/error message.  Looking at the resolution, we may be able to add a private constructor but I’m not certain how that’ll affect SandCastle or if that will cause another fxCop message.

 

    Resolution   : "'NamespaceDoc' is an internal class that is apparently

                   never instantiated. If so, remove the code from the

                   assembly. If this class is intended to contain only

                   static methods, consider adding a private constructor

                   to prevent the compiler from generating a default constructor."

    Info         : "An internal class was detected that is apparently never

                   instantiated. This rule does not attempt to detect

                   late-bound creation and will generate false positives

                   if instances of a type are only created in this way

                   (for example, by means of Activator.CreateInstance

                   or by passing the type as an argument to a TypeConverter

                   constructor)."

Any thoughts on how this could be resolved would be greatly appreciated :)

Bob Hanson

Editor
Dec 3, 2008 at 7:34 PM
Edited Dec 3, 2008 at 7:38 PM
Just make the class private by removing the "internal" keyword.  That way it won't trigger the rule.  In addition, mark it with the System.Runtime.CompilerServices.CompilerGeneratedAttribute so that MRefBuilder strips it from the reflection information automatically.  That way, you don't have to exclude it with the API filter if you ever do a documentation build that includes private types and members.  For example:

namespace APISoftware.Navigator.Constants

{

    /// <summary>Summary goes here.</summary>

    [System.Runtime.CompilerServices.CompilerGeneratedAttribute()]
    class NamespaceDoc{}

}

Eric
Dec 4, 2008 at 12:37 PM
Hi,

Technically, removing the internal keyword does not make the class private.  It remains internal, which is the default, and the only option aside from public, for classes that aren't nested.  I guess you've just found a bug in FxCop ;)

- Dave
Editor
Dec 5, 2008 at 12:56 AM
It's the CompilerGeneratedAttribute that does the trick.  Taking it off brings the message back.  I've always used it so hadn't noticed the FxCop warning before.

Eric