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

docs: enclosing in backticks #169

Closed
LeoniePhiline opened this issue Apr 23, 2024 · 1 comment · Fixed by #170
Closed

docs: enclosing in backticks #169

LeoniePhiline opened this issue Apr 23, 2024 · 1 comment · Fixed by #170

Comments

@LeoniePhiline
Copy link
Contributor

Reading https://docs.rs/eyre/latest/eyre/struct.Report.html#display-representations I found that some items should better be enclosed in backticks.

image

I'll happily fix that, I merely want to ask in advance:

When enclosing parts of strings in backticks, do you then prefer backticks + quotes, or only backticks?

I personally prefer backticks + quotes, to signify "this is code, but it's a string literal".

Here an example (look out for the curly braces):

  1. backticks + quotes: When you print an error object using "{}" or to_string(), only the outermost underlying error is printed, not any of the lower level causes. This is exactly as if you had called the Display impl of the error from which you constructed your eyre::Report. [...] To print causes as well using eyre’s default formatting of causes, use the alternate selector "{:#}".
  2. only backticks: When you print an error object using {} or to_string(), only the outermost underlying error is printed, not any of the lower level causes. This is exactly as if you had called the Display impl of the error from which you constructed your eyre::Report. [...] To print causes as well using eyre’s default formatting of causes, use the alternate selector {:#}.
@pksunkara
Copy link
Contributor

Backticks + quotes is okay. Thanks 😄

LeoniePhiline added a commit to LeoniePhiline/eyre that referenced this issue Apr 24, 2024
yaahc added a commit that referenced this issue Apr 25, 2024
Fixes #169

Besides enclosing inline code in backticks, I also made two tiny
documentation improvements - please let me know if you want them undone:

- In the `Report::msg` docs, the user is referred to `Report::new`. I
changed this from plain inline code into a link.
- I expanded _"`Display` impl"_ to _"`Display` implementation"_, since
`impl` is a Rust token, but
  - _"`Display` `impl`"_ looked silly, and 
  - _"`impl Display`"_ disturbed the flow of reading.

Co-authored-by: Jane Losare-Lusby <jlusby@yaah.dev>
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

Successfully merging a pull request may close this issue.

2 participants