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.

Sign up for GitHub

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

Fix convert module's documentation links #59923

Merged
merged 7 commits into from
May 16, 2019
Merged

Fix convert module's documentation links #59923

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
eba03d4
Fix convert module's documentation links
czipperz Apr 12, 2019
6bf94cd
Remove dangling ` in Into documentation
czipperz Apr 13, 2019
b701d32
Remove broken links to self in Into documentation
czipperz Apr 13, 2019
4a33ece
Remove blank lines in AsRef documentation
czipperz Apr 13, 2019
27ff536
Reorder blank lines in AsMut documentation
czipperz Apr 13, 2019
1e48da6
Escape &str in convert docs
czipperz Apr 13, 2019
1f5d510
Fix stray ` in previous change
czipperz Apr 14, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 20 additions & 20 deletions src/libcore/convert.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -104,7 +104,6 @@ pub const fn identity<T>(x: T) -> T { x }
/// If you need to do a costly conversion it is better to implement [`From`] with type
/// `&T` or write a custom function.
///
///
/// `AsRef` has the same signature as [`Borrow`], but `Borrow` is different in few aspects:
///
/// - Unlike `AsRef`, `Borrow` has a blanket impl for any `T`, and can be used to accept either
Expand Down Expand Up @@ -133,7 +132,7 @@ pub const fn identity<T>(x: T) -> T { x }
/// converted a the specified type `T`.
///
/// For example: By creating a generic function that takes an `AsRef<str>` we express that we
/// want to accept all references that can be converted to &str as an argument.
/// want to accept all references that can be converted to `&str` as an argument.
/// Since both [`String`] and `&str` implement `AsRef<str>` we can accept both as input argument.
///
/// [`String`]: ../../std/string/struct.String.html
Expand All @@ -149,7 +148,6 @@ pub const fn identity<T>(x: T) -> T { x }
/// let s = "hello".to_string();
/// is_hello(s);
/// ```
///
#[stable(feature = "rust1", since = "1.0.0")]
pub trait AsRef<T: ?Sized> {
/// Performs the conversion.
Expand Down Expand Up @@ -182,6 +180,7 @@ pub trait AsRef<T: ?Sized> {
/// write a function `add_one`that takes all arguments that can be converted to `&mut u64`.
/// Because [`Box<T>`] implements `AsMut<T>` `add_one` accepts arguments of type
/// `&mut Box<u64>` as well:
///
/// ```
/// fn add_one<T: AsMut<u64>>(num: &mut T) {
/// *num.as_mut() += 1;
Expand All @@ -191,8 +190,8 @@ pub trait AsRef<T: ?Sized> {
/// add_one(&mut boxed_num);
/// assert_eq!(*boxed_num, 1);
/// ```
/// [`Box<T>`]: ../../std/boxed/struct.Box.html
///
/// [`Box<T>`]: ../../std/boxed/struct.Box.html
#[stable(feature = "rust1", since = "1.0.0")]
pub trait AsMut<T: ?Sized> {
/// Performs the conversion.
Expand All @@ -203,18 +202,18 @@ pub trait AsMut<T: ?Sized> {
/// A value-to-value conversion that consumes the input value. The
/// opposite of [`From`].
///
/// One should only implement [`Into`] if a conversion to a type outside the current crate is
/// required. Otherwise one should always prefer implementing [`From`] over [`Into`] because
/// implementing [`From`] automatically provides one with a implementation of [`Into`] thanks to
/// One should only implement `Into` if a conversion to a type outside the current crate is
/// required. Otherwise one should always prefer implementing [`From`] over `Into` because
/// implementing [`From`] automatically provides one with a implementation of `Into` thanks to
/// the blanket implementation in the standard library. [`From`] cannot do these type of
/// conversions because of Rust's orphaning rules.
///
/// **Note: This trait must not fail**. If the conversion can fail, use [`TryInto`].
///
/// # Generic Implementations
///
/// - [`From<T>`]` for U` implies `Into<U> for T`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please keep this as is and let From<T> be linked to From.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The documentation is inconsistent in this regard. Some places it uses

[`From<T>`]` ...`

other times it uses

[`From`]`<T> ...`

Why do you prefer the former? The latter reduces copy paste of the link destinations.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Otherwise it looks like this: From<T> which doesn't look great.

Copy link
Contributor Author

@czipperz czipperz Apr 12, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See convert module it looks fine

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So should I fix this line too?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Personally I think it looks weird; there's a space in-between that shouldn't be there, but I leave it to Steve.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We don't have a good convention, and I agree the space is unfortunate. Maybe @rust-lang/rustdoc can weigh in?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I tend to prefer how @czipperz wrote it.

Copy link
Contributor Author

@czipperz czipperz Apr 14, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Although the spacing should theoretically be more messed up in the later as @Centril pointed out, it really looks more messed up the former when rendered by rustdoc. Strange. image

Copy link
Contributor Author

@czipperz czipperz Apr 14, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This style (of putting <T> not inside the link) is much less popular than the other way around. Before this pr, its used 40 times throughout the code base vs 168 for the other style.

Edit: my regex was wrong

Here's an example from Weak's documentation:
image

/// - [`Into`]` is reflexive, which means that `Into<T> for T` is implemented
/// - [`From`]`<T> for U` implies `Into<U> for T`
/// - `Into` is reflexive, which means that `Into<T> for T` is implemented
///
/// # Implementing `Into` for conversions to external types
///
Expand Down Expand Up @@ -273,7 +272,7 @@ pub trait AsMut<T: ?Sized> {
/// [`Option<T>`]: ../../std/option/enum.Option.html
/// [`Result<T, E>`]: ../../std/result/enum.Result.html
/// [`String`]: ../../std/string/struct.String.html
/// [From]: trait.From.html
/// [`From`]: trait.From.html
/// [`into`]: trait.Into.html#tymethod.into
#[stable(feature = "rust1", since = "1.0.0")]
pub trait Into<T>: Sized {
Expand All @@ -285,18 +284,18 @@ pub trait Into<T>: Sized {
/// Used to do value-to-value conversions while consuming the input value. It is the reciprocal of
/// [`Into`].
///
/// One should always prefer implementing [`From`] over [`Into`]
/// because implementing [`From`] automatically provides one with a implementation of [`Into`]
/// One should always prefer implementing `From` over [`Into`]
/// because implementing `From` automatically provides one with a implementation of [`Into`]
/// thanks to the blanket implementation in the standard library.
///
/// Only implement [`Into`] if a conversion to a type outside the current crate is required.
/// [`From`] cannot do these type of conversions because of Rust's orphaning rules.
/// `From` cannot do these type of conversions because of Rust's orphaning rules.
/// See [`Into`] for more details.
///
/// Prefer using [`Into`] over using [`From`] when specifying trait bounds on a generic function.
/// Prefer using [`Into`] over using `From` when specifying trait bounds on a generic function.
/// This way, types that directly implement [`Into`] can be used as arguments as well.
///
/// The [`From`] is also very useful when performing error handling. When constructing a function
/// The `From` is also very useful when performing error handling. When constructing a function
/// that is capable of failing, the return type will generally be of the form `Result<T, E>`.
/// The `From` trait simplifies error handling by allowing a function to return a single error type
/// that encapsulate multiple error types. See the "Examples" section and [the book][book] for more
Expand All @@ -306,14 +305,15 @@ pub trait Into<T>: Sized {
///
/// # Generic Implementations
///
/// - [`From<T>`]` for U` implies [`Into<U>`]` for T`
/// - [`From`] is reflexive, which means that `From<T> for T` is implemented
/// - `From<T> for U` implies [`Into`]`<U> for T`
/// - `From` is reflexive, which means that `From<T> for T` is implemented
///
/// # Examples
///
/// [`String`] implements `From<&str>`:
///
/// An explicit conversion from a &str to a String is done as follows:
/// An explicit conversion from a `&str` to a String is done as follows:
///
/// ```
/// let string = "hello".to_string();
/// let other_string = String::from("hello");
Expand Down Expand Up @@ -361,7 +361,7 @@ pub trait Into<T>: Sized {
/// [`Option<T>`]: ../../std/option/enum.Option.html
/// [`Result<T, E>`]: ../../std/result/enum.Result.html
/// [`String`]: ../../std/string/struct.String.html
/// [`Into<U>`]: trait.Into.html
/// [`Into`]: trait.Into.html
/// [`from`]: trait.From.html#tymethod.from
/// [book]: ../../book/ch09-00-error-handling.html
#[stable(feature = "rust1", since = "1.0.0")]
Expand Down Expand Up @@ -422,7 +422,7 @@ pub trait TryInto<T>: Sized {
///
/// # Generic Implementations
///
/// - `TryFrom<T> for U` implies [`TryInto<U>`]` for T`
/// - `TryFrom<T> for U` implies [`TryInto`]`<U> for T`
/// - [`try_from`] is reflexive, which means that `TryFrom<T> for T`
/// is implemented and cannot fail -- the associated `Error` type for
/// calling `T::try_from()` on a value of type `T` is `Infallible`.
Expand Down