Proposal: Allow fine-grained control over when documentation is checked on interfaces

[RobSiklos]

Spawned from #2934 (comment)

Overview
This is a proposal to allow control over how much StyleCop cares about documentation on internal interfaces.

Background
According to the above issue, documentInterfaces=true takes precedence over documentInternalElements = false. This means that if you want StyleCop to check documentation on public interfaces, it will also check documentation on internal interfaces. There is currently no way to have StyleCop check documentation on public interfaces while ignoring internal interfaces.

Rationale
We have many external interfaces and each must have documentation that adheres to all the StyleCop rules. However, for internal interfaces (of which we also have many), we don't care if any of the documentation elements are missing.

Suggested Solution
I propose that the documentInterfaces item in stylecop.json be enhanced to support the following values:

• "all" - (default value) Indicates that documentation on internal as well as public interfaces should be checked.
• "external" - Indicates that documentation should only be checked on interfaces if they are externally visible.
• "none" - Indicates that documentation should not be checked on interfaces (equivalent to "documentInterfaces": false in current behaviour).
• true - For backward compatibility. Equivalent to "all"
• false - For backward compatibility. Equivalent to "none"

Example:

    "documentationRules": {
      "documentInterfaces": "external",
      "documentExposedElements": true,
      "documentInternalElements": false
    }

[sharwell]

I'm 👍 on this, with the one change that we use "exposed" instead of "external" for consistency.

[Ekkeir]

Is there a known state for this feature?
Mandatory documentation for public interfaces, but not external ones would be of great practical use.

[sharwell]

Based on this method, I'm not sure a change is needed here.

StyleCopAnalyzers/StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/SA1600ElementsMustBeDocumented.cs

Line 60 in f5f4ca9

public static bool NeedsComment(DocumentationSettings documentationSettings, SyntaxKind syntaxKind, SyntaxKind parentSyntaxKind, Accessibility declaredAccessibility, Accessibility effectiveAccessibility)

The following should be equivalent to the new external option presented above:

"documentationRules": {
  "documentInterfaces": false,
  "documentExposedElements": true
}

[bjornhellander]

"documentationRules": {
  "documentInterfaces": false,
  "documentExposedElements": true
}

This would require documentation on all exposed types, not just interfaces.

[AraHaan]

"documentationRules": {
  "documentInterfaces": false,
  "documentExposedElements": true
}

This would require documentation on all exposed types, not just interfaces.

if you don't want docs on other types that are public make them internal and use InternalsVisibleTo on the msbuild side itself then.

[sharwell]

Thanks @bjornhellander missed that case.