StyleCop incompatibilities

[vatsan-madhavan]

I'm encountering warnings with the following common StyleCop rules:

• SA1629:Documentation text should end with a period
  • e.g., hard to get something like <url>https://foo:port</url> to have a trailing period.
• SA1612:Element parameter documentation should match element parameters
  • This is especially problematic when using a class argument for e.g., in an Azure Function that abstracts away multiple (actual) arguments and lets the infrastructure handle query-string parsing. A typical function may look like public async Task<IActionResult> Run([HttpTrigger(...)CompositeType args, HttpRequest req) {}, where CompsiteType actually represents something like class {public string a; public int b;}. The OpenApi documentation would require two <param> xml elements corresponding to a and b in this instance, whereas the C# expectation is that only one <param> element corresponding to args is written in the xml doc-comment.
• SA1611:Element parameters should be documented
  • This is also similar to SA1612.

In addition to these, CS1573 (Parameter has no matching param tag in the XML comment) and CS1572 (XML comment has a param tag, but there is no parameter by that name) warnings are also generated - which roughly represent the same problem.

These can be suppressed using pragmas or [SuppressMessage] attributes, of course. That said, (a) it would be great to have clear guidelines for dealing with these sorts of conflicts and (b) over time, some thought could be put into changes either here (or even to StyleCop) to provide better control over suppressing these sorts of warnings more elegantly.