Xml comments cleanup and improvement

[gintsk]

Pull Request

The issue or feature being addressed

Contributes to #1290 by addressing some XML documentation quality issues

Details on the issue fix or feature implementation

Fixes various XML comments quality issues

• Fixes SA1629 "Documentation text should end with a period"
• Fixes CA1200 "Avoid using cref tags with a prefix"
• Fixes SA1627 "The documentation text within the 'exception' tag should not be empty"
• Fixes SA1629 "Documentation text should end with a period" in ArgumentOutOfRangeException (but these could be further improved)
• Fixes SA1614 "Element parameter documentation should have text"
• Unifies XML comments for ArgumentNullException as following

  /// <exception cref="ArgumentNullException">Thrown when <paramref name="parameter"/> is <see langword="null"/>.</exception>"

  as already used in other places. i.e.
  

  Polly/src/Polly.Core/CircuitBreaker/CircuitBreakerResiliencePipelineBuilderExtensions.cs

  Line 26 in 1dba402

  /// <exception cref="ArgumentNullException">Thrown when <paramref name="builder"/> or <paramref name="options"/> is <see langword="null"/>.</exception>

Confirm the following

• I started this PR by branching from the head of the default branch
• I have targeted the PR to merge into the default branch
• I have included unit tests for the issue/feature
• I have successfully run a local build

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 83.64%. Comparing base (1dba402) to head (e18de1a).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2007   +/-   ##
=======================================
  Coverage   83.64%   83.64%           
=======================================
  Files         312      312           
  Lines        7105     7105           
  Branches     1054     1054           
=======================================
  Hits         5943     5943           
  Misses        789      789           
  Partials      373      373           

Flag	Coverage Δ
linux	83.64% <ø> (ø)
macos	83.64% <ø> (ø)
windows	83.64% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[martincostello]

Were there some warnings you meant to turn back on in this commit? Also I'd have expected there to be some compiler warnings here for some of the changes I've noted that are referencing the wrong/missing parameters.

[gintsk]

Were there some warnings you meant to turn back on in this commit?

If I understood you correctly - it would be nice to get compiler warnings about documentation issues. At the moment stylecop documentation warnings are visible only when editing files.

Also I'd have expected there to be some compiler warnings here for some of the changes I've noted that are referencing the wrong/missing parameters.

I guess there are no such code-analysis/stylecop documentation rules. Maybe in some other documentation analyzers.

[martincostello]

Yes, I would have expected the compiler to warn about the references to parameters that didn't exist.

[martincostello]

Yes, I would have expected the compiler to warn about the references to parameters that didn't exist.

So the reason this isn't happening is because we don't set <GenerateDocumentationFile>true</GenerateDocumentationFile>.

If I enable that locally for this branch and build the project, then I get 113 warnings:

[martincostello]

Thanks for all the changes so far - if you'd like to do another PR, I suggest one that enables generation of the documentation file as noted above, and then fixing all of the remaining issues together with that to get us down to zero.