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

Jump to bottom

docs: use intra-links in the docs #2575

Merged
merged 1 commit into from May 31, 2020
Merged

docs: use intra-links in the docs #2575

merged 1 commit into from May 31, 2020

Conversation

ghost
Copy link

@ghost ghost commented May 30, 2020

Motivation

Make doc's links more resistant.

Solution

Delegates doc's links resolution to rustdoc.

Refs: #1473

Darksonn
Darksonn reviewed May 31, 2020
View reviewed changes
tokio/src/coop.rs Outdated
@@ -45,7 +45,7 @@
//! other futures. By doing this, you avoid double-counting each iteration of
//! the outer future against the cooperating budget.
//!
//! [`poll`]: https://doc.rust-lang.org/std/future/trait.Future.html#tymethod.poll
//! [`poll`]: trait@std::future::Future#tymethod.poll
Copy link
Contributor

Choose a reason for hiding this comment

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

This seems like it should link directly to the method.

Copy link
Author

Choose a reason for hiding this comment

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

See link comparison below.. the method is ok, but just found it replaces
std/future with nightly/core

The new link:
https://doc.rust-lang.org/nightly/core/future/trait.Future.html#tymethod.poll
the old link
https://doc.rust-lang.org/std/future/trait.Future.html#tymethod.poll

Any thoughts? :)

Copy link
Author

@ghost ghost May 31, 2020 •
edited by ghost
Loading

Choose a reason for hiding this comment

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

Just checked another similar link, and we have

new
https://doc.rust-lang.org/nightly/std/fs/fn.remove_dir_all.html
old
https://doc.rust-lang.org/std/fs/fn.remove_dir_all.html

this is correct, except ;) it uses nightly, LOL

Copy link
Author

@ghost ghost May 31, 2020 •
edited by ghost
Loading

Choose a reason for hiding this comment

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

the method is ok

Actually, @Darksonn is right it will be cleaner to make it
method@std::future::Future::poll

However, even then we still have other issues, like

  1. std/future (old) vs core/future (new)
  2. std (old) vs nightly (new)

Copy link
Contributor

Choose a reason for hiding this comment

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

It seems like docs.rs manages to convince rustdoc that they should be links to the stable std. Maybe we can figure out how rustdoc does it?

Copy link
Contributor

Choose a reason for hiding this comment

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

This works, but the -Z unstable-options is a bit uncomfortable.

RUSTDOCFLAGS="--cfg docsrs -Z unstable-options --extern-html-root-url std=https://doc.rust-lang.org/stable/" cargo +nightly doc --all-features

Copy link
Author

Choose a reason for hiding this comment

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

one way or another, switching that should be a separate MR/Issue

Copy link
Author

Choose a reason for hiding this comment

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

Regardless of the std vs nightly issue, the rest two comments I just fixed.

Copy link
Contributor

Choose a reason for hiding this comment

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

No, the nightly vs std issue doesn't block this PR. It wasn't caused by it, after all.

Copy link
Author

Choose a reason for hiding this comment

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

so, should we merge it? :)

tokio/src/lib.rs Outdated Show resolved Hide resolved
@Darksonn Darksonn added A-tokio Area: The main tokio crate A-tokio-util Area: The tokio-util crate C-maintenance Category: PRs that clean code up or issues documenting cleanup. T-docs Topic: documentation labels May 31, 2020
@ghost ghost mentioned this pull request May 31, 2020
Closed
@Darksonn Darksonn merged commit e70a1b6 into tokio-rs:master May 31, 2020
jensim pushed a commit to jensim/tokio that referenced this pull request Jun 7, 2020
@jensim
docs: use intra-links in the docs (tokio-rs#2575)
7367abc
hawkw added a commit that referenced this pull request Jul 20, 2020
@hawkw
chore: prepare to release 0.2.22
972c717 
- docs: misc improvements (#2572, #2658, #2663, #2656, #2647, #2630, #2487, #2621,
  #2624, #2600, #2623, #2622, #2577, #2569, #2589, #2575, #2540, #2564, #2567,
  #2520, #2521, #2572, #2493)
- rt: allow calls to `block_on` inside calls to `block_in_place` that are
  themselves inside `block_on` (#2645)
- net: fix non-portable behavior when dropping `TcpStream` `OwnedWriteHalf` (#2597)
- io: improve stack usage by allocating large buffers on directly on the heap
  (#2634)
- io: fix unsound pin projection in `AsyncReadExt::read_buf` and
  `AsyncWriteExt::write_buf` (#2612)
- io: fix unnecessary zeroing for `AsyncRead` implementors (#2525)
- io: Fix `BufReader` not correctly forwarding `poll_write_buf` (#2654)

- coop: returning `Poll::Pending` no longer decrements the task budget (#2549)

- io: little-endian variants of `AsyncReadExt` and `AsyncWriteExt` methods
  (#1915)
- io: fix panic in `AsyncReadExt::read_line` (#2541)
- task: add [`tracing`] instrumentation to spawned tasks (#2655)
- sync: allow unsized types in `Mutex` and `RwLock` (via `default` constructors)
  (#2615)
- net: add `ToSocketAddrs` implementation for `&[SocketAddr]` (#2604)
- fs: add `OpenOptionsExt` for `OpenOptions` (#2515)
- fs: add `DirBuilder` (#2524)

[`tracing`]: https://crates.io/crates/tracing

Signed-off-by: Eliza Weisman <eliza@buoyant.io>
@hawkw hawkw mentioned this pull request Jul 20, 2020
Merged
hawkw added a commit that referenced this pull request Jul 22, 2020
@hawkw
chore: prepare to release 0.2.22 (#2672)
21f7260 
# 0.2.22 (July 2!, 2020)

### Fixes
- docs: misc improvements (#2572, #2658, #2663, #2656, #2647, #2630, #2487, #2621,
  #2624, #2600, #2623, #2622, #2577, #2569, #2589, #2575, #2540, #2564, #2567,
  #2520, #2521, #2493)
- rt: allow calls to `block_on` inside calls to `block_in_place` that are
  themselves inside `block_on` (#2645)
- net: fix non-portable behavior when dropping `TcpStream` `OwnedWriteHalf` (#2597)
- io: improve stack usage by allocating large buffers on directly on the heap
  (#2634)
- io: fix unsound pin projection in `AsyncReadExt::read_buf` and
  `AsyncWriteExt::write_buf` (#2612)
- io: fix unnecessary zeroing for `AsyncRead` implementors (#2525)
- io: Fix `BufReader` not correctly forwarding `poll_write_buf` (#2654)
- io: fix panic in `AsyncReadExt::read_line` (#2541)

### Changes
- coop: returning `Poll::Pending` no longer decrements the task budget (#2549)

### Added
- io: little-endian variants of `AsyncReadExt` and `AsyncWriteExt` methods
  (#1915)
- task: add [`tracing`] instrumentation to spawned tasks (#2655)
- sync: allow unsized types in `Mutex` and `RwLock` (via `default` constructors)
  (#2615)
- net: add `ToSocketAddrs` implementation for `&[SocketAddr]` (#2604)
- fs: add `OpenOptionsExt` for `OpenOptions` (#2515)
- fs: add `DirBuilder` (#2524)

[`tracing`]: https://crates.io/crates/tracing

Signed-off-by: Eliza Weisman <eliza@buoyant.io>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
A-tokio Area: The main tokio crate A-tokio-util Area: The tokio-util crate C-maintenance Category: PRs that clean code up or issues documenting cleanup. T-docs Topic: documentation
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
1 participant
@Darksonn