Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Xml documentation cleanup #2008

Merged
merged 10 commits into from
Mar 5, 2024

Conversation

gintsk
Copy link
Contributor

@gintsk gintsk commented Mar 5, 2024

Pull Request

The issue or feature being addressed

Contributes to #1290 by further addressing some XML documentation quality issues as noted in #2007

Details on the issue fix or feature implementation

  • Enables generation of the documentation file for Polly project, so we get documentation related compiler warnings.
  • Fixes identified XML comments quality issues:
  • CS1734 "XML comment on '{1}' has a paramref tag for '{0}', but there is no parameter by that name"
  • CS1658 "Type parameter declaration must be an identifier not a type."
  • SA1616 "Element return value documentation should have text"
  • SA1648 "inheritdoc should be used with inheriting class"
  • SA1642 "Constructor summary documentation should begin with standard text"
  • SA1629 "Documentation text should end with a period"
  • SA1619 "The documentation for type parameter 'TResult' is missing"
  • CA1200 "Avoid using cref tags with a prefix"
  • SA1600 "Elements should be documented"

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

Copy link

codecov bot commented Mar 5, 2024

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 83.64%. Comparing base (8a1f276) to head (004bb80).

Additional details and impacted files
@@           Coverage Diff           @@
##             main    #2008   +/-   ##
=======================================
  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.

Copy link
Member

@martincostello martincostello left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks again!

@@ -37,7 +37,7 @@ bool TryRemove<TPolicy>(TKey key, out TPolicy policy)
/// <param name="key">The key whose value is compared with comparisonPolicy, and possibly replaced.</param>
/// <param name="newPolicy">The policy that replaces the value for the specified <paramref name="key"/>, if the comparison results in equality.</param>
/// <param name="comparisonPolicy">The policy that is compared to the existing policy at the specified key.</param>
/// <returns></returns>
/// <returns>True if the policy is successfully updated. Otherwise false.</returns>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could use langword for these like we do for null.

@martincostello martincostello added this to the v8.3.1 milestone Mar 5, 2024
@martincostello martincostello merged commit 613279e into App-vNext:main Mar 5, 2024
17 checks passed
@gintsk gintsk deleted the xml-documentation-cleanup branch March 5, 2024 21:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants