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

Improve Rustdoc self-documentation visibility by displaying links in usage #76427

Conversation

AndyGauge
Copy link
Contributor

@AndyGauge AndyGauge commented Sep 7, 2020

fixes #75520

andy@DESKTOP-20F0LAL:/mnt/d/git/rust$ rustdoc +stage1 --help
rustdoc usage is documented online https://doc.rust-lang.org/rustdoc/
nightly rustdoc includes additional features https://doc.rust-lang.org/nightly/nightly-rustc/rustdoc/
rustdoc [options] <input>

@rust-highfive
Copy link
Collaborator

r? @ollie27

(rust_highfive has picked a reviewer for you, use r? to override)

@rust-highfive rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Sep 7, 2020
@jyn514 jyn514 added the T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. label Sep 7, 2020
@jyn514
Copy link
Member

jyn514 commented Sep 8, 2020

Hmm, I'm a little unsure about this. None of the other tools do anything similar (I tried rustc, cargo, rustfmt). On the other hand, rg does link to the homepage, as do a couple other CLI tools I tried. @GuillaumeGomez what do you think?

Copy link
Member

@jyn514 jyn514 left a comment

Choose a reason for hiding this comment

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

Could you also print this message after the rustdoc [options] <input> snippet, not before?

Comment on lines +407 to +410
println!("rustdoc usage is documented online https://doc.rust-lang.org/rustdoc/");
if nightly_options::is_nightly_build() {
println!("nightly rustdoc includes additional features https://doc.rust-lang.org/nightly/nightly-rustc/rustdoc/");
}
Copy link
Member

@jyn514 jyn514 Sep 8, 2020

Choose a reason for hiding this comment

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

This should only link to one or the other I think.

Suggested change
println!("rustdoc usage is documented online https://doc.rust-lang.org/rustdoc/");
if nightly_options::is_nightly_build() {
println!("nightly rustdoc includes additional features https://doc.rust-lang.org/nightly/nightly-rustc/rustdoc/");
}
let url = if nightly_options::is_nightly_build() {
"https://doc.rust-lang.org/nightly/rustdoc/"
} else {
"https://doc.rust-lang.org/rustdoc/"
};
println!("Documentation: {}", url);

@GuillaumeGomez
Copy link
Member

I'm really unsure about this too... This is an interesting take to the problem though...

@crlf0710
Copy link
Member

@AndyGauge Ping from triage, CI is still red here. Would you mind fixing it? Also, please try to discuss this will rustdoc team to reach agreement on this, maybe by asking on rustdoc channel on Discord.

@jyn514 jyn514 added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Oct 13, 2020
@camelid camelid changed the title Improve Rustdoc visibility by displaying links in usage Improve Rustdoc self-documentation visibility by displaying links in usage Oct 30, 2020
@camelid camelid added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Oct 30, 2020
@Dylan-DPC-zz
Copy link

@AndyGauge thanks for taking the time to contribute. I have to close this due to inactivity. If you wish and you have the time you can open a new PR with these changes and we'll take it from there. Thanks

@Dylan-DPC-zz Dylan-DPC-zz added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Oct 30, 2020
@AndyGauge
Copy link
Contributor Author

Yeah, I think I misunderstood the requirements 💯

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Improve "visibility" of rustdoc books ("stable" and unstable ones)
8 participants