Skip to content

Documentation: Bullet list in Deref documentation not working, causing confusing #43866

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

Closed
kumbayo opened this issue Aug 14, 2017 · 2 comments
Closed
Labels
A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools C-bug Category: This is a bug.

Comments

@kumbayo
Copy link

kumbayo commented Aug 14, 2017

The documentation of Deref/DerefMut wants to show a list with 3 bullet points.
https://doc.rust-lang.org/nightly/std/ops/trait.Deref.html#more-on-deref-coercion

But instead all 3 list entries are squashed together into a single block separated by 3 * characters.

deref_strange_list

This * character is a bit confusing in the context of dereferencing operations which uses the *.

In other parts of the documentation, bullet list seem to work normally.
https://doc.rust-lang.org/nightly/std/primitive.f32.html#method.atan2
Not sure what the difference is here.

CC @lukaramu You seem to have added these in 5990be5

@steveklabnik
Copy link
Member

see https://github.com/rust-lang/rust/blob/master/src/libcore/ops/deref.rs#L29-L33

vs

rust/src/libstd/f32.rs

Lines 870 to 873 in af049cd

/// * `x = 0`, `y = 0`: `0`
/// * `x >= 0`: `arctan(y/x)` -> `[-pi/2, pi/2]`
/// * `y >= 0`: `arctan(y/x) + pi` -> `(pi/2, pi]`
/// * `y < 0`: `arctan(y/x) - pi` -> `(-pi, -pi/2)`

I have a hunch that you need an extra line of whitespace before the list. We should do it anyway, but that may or may not also fix this issue.

@steveklabnik steveklabnik added C-bug Category: This is a bug. A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools labels Aug 14, 2017
@chordowl
Copy link
Contributor

That was probably caused by me being used to GitHub's markdown implementation, in which the extra whitespace line is not required 😅

I'll send out a fix PR!

frewsxcv added a commit to frewsxcv/rust that referenced this issue Aug 15, 2017
Add missing newline in Deref docs to fix rendering

Fixes rust-lang#43866.

(Verified locally.)

r? @steveklabnik
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools C-bug Category: This is a bug.
Projects
None yet
Development

No branches or pull requests

3 participants