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

Link to documentation-specific guidelines. #77195

Merged
merged 1 commit into from
Oct 10, 2020
+1 −1
Merged

Link to documentation-specific guidelines. #77195

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 library/std/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -85,7 +85,7 @@
//! # Contributing changes to the documentation
//!
//! Check out the rust contribution guidelines [here](
//! https://rustc-dev-guide.rust-lang.org/getting-started.html).
//! https://rustc-dev-guide.rust-lang.org/contributing.html#writing-documentation).
//! The source for this documentation can be found on
//! [GitHub](https://github.com/rust-lang/rust).
Copy link
Contributor

Choose a reason for hiding this comment

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

This doesn't seem specific, should we change this too?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Are you referring to the [GitHub](https://github.com/rust-lang/rust) link?

If so, yeah, I was working toward suggesting a PR for that too but it was a bit less "obvious" fix so was limiting this PR to just the one change.

The main question/issue I see is that the "Writing Documentation" section includes this sentence:

The source of doc.rust-lang.org is located in src/doc in the tree, and standard API documentation is generated from the source code itself.

So, depending on what "this documentation" is intended to refer to it's unclear whether the best approach is:

  1. Link to library/std/src/lib.rs
  2. Remove "The source for this documentation..." sentence entirely.
  3. Replace "The source for this documentation..." sentence with "The source of doc.rust-lang.org is located in src/doc in the tree, and standard API documentation is generated from the source code itself (e.g. lib.rs)." (And/or make the link additions to https://rustc-dev-guide.rust-lang.org/contributing.html.)

Copy link
Contributor

Choose a reason for hiding this comment

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

I think you could just include another suggestion here along with the patch. But I think linking to library/std/src/lib.rs isn't good enough since people may want to edit other files.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I've put a PR in the dev guide repo with option 3: rust-lang/rustc-dev-guide#898

If that PR gets merged then perhaps we can decide if there's an issue with duplicating the content here?

The example link to library/std/src/lib.rs was (a) the literal source for the documentation in question :) and (b) just intended as an example to help people start looking in the right place. Open to other suggestions of where to link instead.

Adding multiple commits to a PR via the GitHub interface (as I'm currently doing for such "drive-by" contributions) is complicated due to the inability to--if I recall correctly--squash commits as required by Rust? (Or maybe that's a per-repo configuration setting?) So, if it's possible to just fix the one issue in this PR, that would be preferable on my part. :)

Copy link
Member

Choose a reason for hiding this comment

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

Adding multiple commits to a PR via the GitHub interface (as I'm currently doing for such "drive-by" contributions) is complicated due to the inability to--if I recall correctly--squash commits as required by Rust?

See also rust-lang/triagebot#821

Copy link
Member

Choose a reason for hiding this comment

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

So, if it's possible to just fix the one issue in this PR, that would be preferable on my part

I think it makes sense to have the changes in one place so it's easier to find all the discussion. I won't block on squashing the commits :)

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Approach A

Based on the now merged #898, one possible approach is something like:

Suggested change
//! [GitHub](https://github.com/rust-lang/rust).
//! [GitHub](https://github.com/rust-lang/rust).
//! Standard API documentation is generated from
//! the source code itself (e.g. [`lib.rs`]) and the
//! source of `doc.rust-lang.org` is located in [`src/doc`] in the tree.
//!
//! [`lib.rs`]: https://github.com/rust-lang/rust/blob/master/library/std/src/lib.rs#L1
//! [`src/doc`]: https://github.com/rust-lang/rust/tree/master/src/doc

But if this file is being viewed via https://doc.rust-lang.org/std/index.html#contributing-changes-to-the-documentation then that wording seems potentially confusing?

Approach B

An alternate wording:

This document and other Standard API documentation is generated from the source code itself (e.g. lib.rs) which can be found in library/ on GitHub.

Source for other documentation hosted on doc.rust-lang.org is located in src/doc.

(Given the content of the latter paragraph is now already mentioned elsewhere, I'm not sure that it's necessarily justified to mention it here.)

Copy link
Member

Choose a reason for hiding this comment

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

But if this file is being viewed via https://doc.rust-lang.org/std/index.html#contributing-changes-to-the-documentation then that wording seems potentially confusing?

Hmm, that doesn't seem too confusing to me: It says the documentation for the standard library lives in the source code for the standard library. I think lib.rs is a little confusing though, maybe say library/std instead.

Both of your approaches seem fine to me, I think both are more clear than the current links.

//! To contribute changes, make sure you read the guidelines first, then submit
Expand Down