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

Warn against here-links in doc comments #13480

Open
SabrinaJewson opened this issue Sep 30, 2024 · 0 comments
Open

Warn against here-links in doc comments #13480

SabrinaJewson opened this issue Sep 30, 2024 · 0 comments
Labels
A-lint Area: New lints

Comments

@SabrinaJewson
Copy link
Contributor

What it does

Warns when a user writes [here], [click here], [link] or [this link] in a doc comment. This lint would be in the “Style” category, as I think it is fairly universally agreed-upon that such links should be avoided (I have not seen arguments to the contrary, at least).

Advantage

Links of this form are widely considered bad for accessibility[1][2][3], among other reasons. It is recommended to change the link text to a short description of what is at the URL instead.

Drawbacks

Sometimes it is non-obvious how to rewrite a here-link into the preferred form, which could increase friction when writing docs.

Example

/// For more details on this function, click [here](crate).

Could be written as:

/// For more details on this function, see [the crate-level docs](crate).
@SabrinaJewson SabrinaJewson added the A-lint Area: New lints label Sep 30, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-lint Area: New lints
Projects
None yet
Development

No branches or pull requests

1 participant