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

Hyperlink crate items in docs #79

Closed
twitu opened this issue Oct 12, 2022 · 0 comments · Fixed by #91
Closed

Hyperlink crate items in docs #79

twitu opened this issue Oct 12, 2022 · 0 comments · Fixed by #91
Labels
documentation Improvements or additions to documentation

Comments

@twitu
Copy link
Collaborator

twitu commented Oct 12, 2022

Rust docs makes it easy to hyperlink doc items by name. This makes it easier to navigate the docs because the reader can quickly jump to the definition of an item being referred.

That being said hyperlinking everything everywhere can make the docs look noisy and hinder readability. This is somewhat subjective but some general rules of thumb -

  • Only need to hyperlink items in this crate
  • If an items is mentioned multiple times in a paragraph or couple of paragraphs, hyperlinking the first time it's mentioned is good enough
  • If a many items from a module are enumerated (like in bulleted list) hyperlinking the module is good enough

from discussion in #73

@twitu twitu added the documentation Improvements or additions to documentation label Oct 12, 2022
@encody encody closed this as completed in #91 Nov 4, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

Successfully merging a pull request may close this issue.

1 participant