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 link in doc comment to ready #2177

Closed
wants to merge 1 commit into from
Closed

Fix link in doc comment to ready #2177

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
2 changes: 1 addition & 1 deletion futures-util/src/future/ready.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ use core::pin::Pin;
use futures_core::future::{FusedFuture, Future};
use futures_core::task::{Context, Poll};

/// Future for the [`ready`](ready()) function.
Copy link
Member

Choose a reason for hiding this comment

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

This is necessary to avoid the ambiguity between future::ready function and ready! macro.

error: `ready` is both a function and a macro
 --> futures-util/src/future/ready.rs:5:21
  |
5 | /// Future for the [`ready`] function.
  |                     ^^^^^^^ ambiguous link
  |
  = note: `-D intra-doc-link-resolution-failure` implied by `-D warnings`
help: to link to the function, add parentheses
  |
5 | /// Future for the [`ready()`] function.
  |                     ^^^^^^^^^
help: to link to the macro, add an exclamation mark
  |
5 | /// Future for the [`ready!`] function.
  |                     ^^^^^^^^

https://travis-ci.com/github/rust-lang/futures-rs/jobs/347600517#L281-L312

Copy link
Author

Choose a reason for hiding this comment

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

Hmm, oops... For some reason, the link works properly for the docs.rs build of futures-util (https://docs.rs/futures-util/0.3.5/futures_util/future/struct.Ready.html links to https://docs.rs/futures-util/0.3.5/futures_util/future/fn.ready.html), but not for futures (https://docs.rs/futures/0.3.5/futures/future/struct.Ready.html links to https://docs.rs/futures/0.3.5/futures/future/ready()).

Copy link
Member

Choose a reason for hiding this comment

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

Hm, seems all of the links to free function are broken: https://docs.rs/futures/0.3.5/futures/future/index.html#structs

The workaround I know is to use fn.ready.html. (I'm not sure how to fix this with intra-doc-link. intra-doc-link still has many bugs...)

Copy link
Member

Choose a reason for hiding this comment

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

It would be very good to make a minimal repro of this and open an issue upstream. Testing locally it appears it's not fixed by rust-lang/rust#73101.

Copy link
Member

Choose a reason for hiding this comment

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

I think this is because you're using [.`join`](join()), and the markdown parser doesn't like that. Either use [`join()`] or use [`join`](function@join).

Copy link
Member

Choose a reason for hiding this comment

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

Nope, never mind

Copy link
Member

Choose a reason for hiding this comment

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

This is because of the funky reexport

rust-lang/rust#73363

A quick fix would be to move that reexport to the bottom of the file, though since cross-crate stuff isn't working great anyway, might as well wait for rust-lang/rust#73101

Copy link
Member

Choose a reason for hiding this comment

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

rust-lang/rust#73365 should land very soon

/// Future for the [`ready`] function.
#[derive(Debug, Clone)]
#[must_use = "futures do nothing unless you `.await` or poll them"]
pub struct Ready<T>(Option<T>);
Expand Down