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

[Tracking] The repo needs clear rules for use of "see cref" and "see langword" attributes #12186

Open
paul1956 opened this issue Sep 20, 2024 · 1 comment
Milestone

Comments

@paul1956
Copy link
Contributor

paul1956 commented Sep 20, 2024

Inconsistent use of the "see cref" attribute.

  1. It is used for every occurrence where it could be used (all places VS has a code fix), including summary and return/value sections. This really clutters the documentation.
  2. It is used once in summary and not in return/value where it could be used also.
  3. It is used in return/value but not in summary where it could be.
  4. It is not used at all typically where the target is not fully qualified, so VS will not offer a CodeFix but there are also times it will and it isn't used.

Inconsistent use of the "see langword" attribute.

  1. It is seldomly used where it could be. true/True, false/False, null/Nothing, Property, Event, I don't know the full list but the CodeFix does.

Guideline would be great; I am not suggesting anyone has to go back and fix everything especially without a CodeAnalyzer (unless it was standalone it would be horribly slow and would produce too may incorrect results) but as code is touched it would be nice to have consistent rules.

@JeremyKuhne
Copy link
Member

Everywhere there is something that can be see cref or see langword they should be. Related, docs should try to use <inheritdoc> with modifications whenever possible instead of duplicating large swaths of text. This is facilitated by not cref'ing argument Types. For example:

/// <inheritdoc cref="DrawRoundedRectangle(Pen, RectangleF, SizeF)"/>
public void DrawRoundedRectangle(Pen pen, Rectangle rect, Size radius) =>
DrawRoundedRectangle(pen, (RectangleF)rect, radius);
/// <summary>
/// Draws the outline of the specified rounded rectangle.
/// </summary>
/// <param name="pen">The <see cref="Pen"/> to draw the outline with.</param>
/// <param name="rect">The bounds of the rounded rectangle.</param>
/// <param name="radius">The radius width and height used to round the corners of the rectangle.</param>
public void DrawRoundedRectangle(Pen pen, RectangleF rect, SizeF radius)

Note that cref doesn't support ?, but the fixer will create them with ?. Removing the ?s will make the link work correctly.

cc: @lonitra

@JeremyKuhne JeremyKuhne added this to the .NET 10.0 milestone Sep 24, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants