75521 rustdoc book improvements by AndyGauge · Pull Request #75778 · rust-lang/rust

AndyGauge · 2020-08-21T17:38:27Z

Added some guidelines about documenting with rustdoc
Fixes#75521

rust-highfive · 2020-08-21T17:38:30Z

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

GuillaumeGomez · 2020-08-21T17:59:26Z

I was wondering: do we have to keep two whitespaces between sentences? cc @rust-lang/docs

GuillaumeGomez · 2020-08-21T18:00:56Z

Suggested change
There's two problems with this: first, why does it
There are two problems with this: first, why does it

I agree, I'll re-read it looking for more of these.

I thought it looked more natural as a contraction, but either way is fine as long as it's consistent.

GuillaumeGomez · 2020-08-21T18:07:58Z

This is a great start! I think if we should also talk more about the arguments that allows to customize the HTML output (for example, adding themes or adding your own JS/CSS files, etc...). We can do that in another PR though (but if so, don't mark this PR as a fix for #75521 ;) ).

GuillaumeGomez · 2020-08-21T18:08:38Z

Oh also: I'll definitely need a native english person to double-check the typos and other things. :)

AndyGauge · 2020-08-21T18:10:27Z

I agree with the themes included in this PR. Should I adjust the title to include work in process?

GuillaumeGomez · 2020-08-21T18:12:27Z

Well, it remains "rustdoc improvements", so it's fine. But you might want to expand the description of the PR a bit if you do it in this PR. ;)

Dylan-DPC-zz

initial review tidbits, just felt it reads better, can ignore if you wish :D

jyn514

I may have gone a little overboard.

jyn514 · 2020-08-22T16:08:07Z

+The first line of description will be reused to describe the component in
+searches and module overviews. For example, the function `std::env::args()`
+above will be shown on the [`std::env`] module documentation. Multi-line
+summaries are also possible, however, concise writing is a goal of good
+documentation.


This is still not correct - it implies that only the first line of a multi-line summary will be shown. It should say that everything before a line break will be shown, but it's good practice to only have one line in the summary.

jyn514 · 2020-08-22T16:08:57Z

 ## Basic usage

-Let's give it a try! Let's create a new project with Cargo:
+Let us give it a try! Create a new project with Cargo:


This also seems really stilted.

bors · 2020-09-14T13:07:29Z

☔ The latest upstream changes (presumably #75740) made this pull request unmergeable. Please resolve the merge conflicts.

Note that reviewers usually do not review pull requests until merge conflicts are resolved! Once you resolve the conflicts, you should change the labels applied by bors to indicate that your PR is ready for review. Post this as a comment to change the labels:

@rustbot modify labels: +S-waiting-on-review -S-waiting-on-author

jyn514

This mostly looks good to me - there's a lot of new information, thank you so much! I'm still a little unsure about expanding out all the contractions (especially since some have been missed, and it's now a little inconsistent).

Also this adds a link to the rustdoc book when you pass --help, I'm not sure how I feel about that (#76427 (comment)). Maybe remove it for now and add it to #76427, so this PR won't be blocked on it?

AndyGauge · 2020-09-14T19:45:23Z

Thanks for the feedback. Looks like there was an accidental merging of 2 tasks, thanks for identifying that. I'm a bit swamped now, but maybe this weekend I'll put some time into this.

jyn514

I think any more changes can be done as follow-ups, this already looks really good. If you split out the change linking to the rustdoc book I think this ready to go.

GuillaumeGomez · 2020-10-19T09:33:11Z

It just requires to rebase to fix the merge conflict and then it's good to go!

AndyGauge · 2020-10-30T16:58:07Z

I will get this done. We moved and that's been taking all my time lately.

jyn514 · 2020-10-30T17:40:47Z

No worries! Thanks for writing this up, it's super helpful :) If you find you don't have time to finish it up I can rebase it myself, too.

jyn514

Normally we use a rebase-only workflow for PRs: https://rustc-dev-guide.rust-lang.org/git.html#no-merge-policy. Do you mind rebasing this instead to get rid of the merge conflict? There are instructions in https://rustc-dev-guide.rust-lang.org/git.html#rebasing, if you have trouble let me know and I'm happy to help.

AndyGauge · 2020-11-04T18:26:46Z

I will, this was a 2 step process, making sure my master merge didn’t bring in extra artifacts. I was nervous I might lose my history. Thank you for the instructions!

Co-authored-by: Joshua Nelson <joshua@yottadb.com>

AndyGauge · 2020-11-06T17:15:05Z

@jyn514 we good now?

jyn514 · 2020-11-06T17:16:34Z

Looks great, thanks!

@bors r+

bors · 2020-11-06T17:16:35Z

📌 Commit 881820a has been approved by jyn514

AndyGauge · 2020-11-06T18:36:37Z

wohoo!

bors · 2020-11-06T19:01:16Z

⌛ Testing commit 881820a with merge a601302...

bors · 2020-11-06T21:48:04Z

☀️ Test successful - checks-actions
Approved by: jyn514
Pushing a601302 to master...

rust-highfive assigned GuillaumeGomez Aug 21, 2020

rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Aug 21, 2020

GuillaumeGomez reviewed Aug 21, 2020
View reviewed changes

Comment threadsrc/doc/rustdoc/src/how-to-write-documentation.md Outdated

GuillaumeGomez reviewed Aug 21, 2020
View reviewed changes

Comment threadsrc/doc/rustdoc/src/what-to-include.md Outdated