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

Add links to types in documentation #372

Closed
CryZe opened this issue Nov 19, 2020 · 2 comments · Fixed by #596
Closed

Add links to types in documentation #372

CryZe opened this issue Nov 19, 2020 · 2 comments · Fixed by #596
Labels
code quality Affects the quality of the code. enhancement An improvement for livesplit-core. suitable for contributions The issue is suitable those who are contributing to livesplit-core. work in progress Someone is working on this.

Comments

@CryZe
Copy link
Collaborator

CryZe commented Nov 19, 2020

Rust 1.48 just came out with a proper built-in way to mention types in documentation that you can click on and get linked to that specific type. Before you needed to write the relative URL of the type which was both cumbersome and based on an implementation detail, so we just never linked to any types. Here's the blog post:

Rust 1.48

@CryZe CryZe added code quality Affects the quality of the code. enhancement An improvement for livesplit-core. suitable for contributions The issue is suitable those who are contributing to livesplit-core. labels Nov 19, 2020
@CryZe CryZe added the work in progress Someone is working on this. label Dec 26, 2020
@Eein
Copy link
Contributor

Eein commented Nov 6, 2022

I've started a little work on this. I've attempted to avoid changing as much of the wording as possible for now; however I feel like some things are looking to busy now: See:

image

The rules i've been following is to only link to things when they're describing another module; if they are describing themselves I simply backticked them to still display them as formatted text.

I suppose a simple wording change for things describing themselves may help a bit:

For example:

timing - The timing module provides everything necessary for working with times and measuring them.
TimeSpan - A TimeSpan represents a certain span of time.

could be:

timing - Provides functions for working with times and measuring them.
TimeSpan - Represents a specific span of time.

I can likely expand on the documentation later in a different unit of work once the initial types are done; following the recommendations by: https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html#documenting-components

For example, if you include a blank line between the first and second paragraphs, it will only return the first sentence to summarize and allow you to add detail when you click through to the actual Struct/Enum/etc

@CryZe
Copy link
Collaborator Author

CryZe commented Nov 6, 2022

Yeah that sounds fine.

@CryZe CryZe linked a pull request Nov 14, 2022 that will close this issue
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
code quality Affects the quality of the code. enhancement An improvement for livesplit-core. suitable for contributions The issue is suitable those who are contributing to livesplit-core. work in progress Someone is working on this.
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants