How to get Stylecop to stop complaining when documenting namespaces using Sandcastle?

Question

I'm trying to document my namespaces as recommended by this StackOverflow answer:

namespace Test
{
    /// <summary>
    /// The documentation for my namespace goes here.
    /// </summary>
    [System.Runtime.CompilerServices.CompilerGenerated]
    internal class NamespaceDoc
    {
    }

    // (other classes below...)
}

However, adding this to my file caused StyleCop to emit several errors. Specifically, it complained that a document can contain only a single class at the root level (SA1402) and that all internal classes must be after public classes (SA1202).

I was able to get StyleCop to ignore the second warning by adding:

[System.Diagnostics.CodeAnalysis.SuppressMessage(
    "StyleCop.CSharp.OrderingRules", 
    "*", 
    Justification = "Hack for Sandcastle.")]

However, I wasn't able to get it to ignore the first warning. I tried applying another attribute, but that didn't do the trick:

[System.Diagnostics.CodeAnalysis.SuppressMessage(
    "StyleCop.CSharp.Maintainability", 
    "*", 
    Justification = "Hack for Sandcastle.")]

What's the best way to get Sandcastle and StyleCop to play nice?

I know I can change the settings within the Sandcastle help file builder to document namespaces, but I'd rather not unless I need to because I want all the documentation to be available at the source code level. I also don't want to completely disable the rules altogether, because they are useful in most circumstances.

Answer 1

Just for the sake of reference, I though I should document what I ended up doing.

Basically, I just created a new .cs file for each namespace I had (for example, FooDoc.cs for the Foo namespace), and formatted my code like so:

// <copyright file="FooDoc.cs" company="Bar Company">
//      Copyright (c) 2013 Bar Company. All rights reserved.
// </copyright>

namespace Foo
{
    /// <summary>
    /// Documentation here.
    /// </summary>
    [System.Runtime.CompilerServices.CompilerGenerated]
    internal class FooDoc
    {
    }
}

It's a little on the hackish side, since I'm basically adding an extra file just to document my namespaces, but it does let me keep my documentation 100% within the project and Sandcastle-compatible without upsetting either Stylecop or other code analysis tools that I've been using.

Answer 2

I don't think there is any solution out of the box. I think the best thing you can do while still keeping things clean is to implement your own StyleCop rule. You may consider a rule that triggers rules SA1402 and SA1202 unless under a "SandCastle context". Then in your StyleCop configuration you disable the rules SA1402 and SA1202.

You can have a look at how to create a rule for StyleCop following this link.