Add a chapter on reading Rustdoc output #90487

NoraCodes · 2021-11-01T21:47:00Z

Includes documentation for:

general page structure
navigation
searching
themes
deep-linking

Doesn't include docs on the settings page.

Per #90309

rust-highfive · 2021-11-01T21:47:03Z

r? @GuillaumeGomez

(rust-highfive has picked a reviewer for you, use r? to override)

GuillaumeGomez · 2021-11-01T21:48:51Z

src/doc/rustdoc/src/how-to-read-rustdoc.md

+The `rustdoc` output is divided into three sections.
+Along the left side of each page is a quick navigation bar,
+which shows contextual information about the current entry.
+The rest of the is taken up by the search interface at the top


"of the page" I guess?

LOL, yes, thanks!

GuillaumeGomez · 2021-11-01T21:49:18Z

src/doc/rustdoc/src/how-to-read-rustdoc.md

+
+## The Item Documentation
+
+The majority of the screen is taken up with the main event:


"the main event"?

English (American?) idiom meaning "the point" - think what data is to metadata. If it confused you, though, it'll confuse others, so I'll change it.

It sounds a bit funny to me too. I'd suggest something like "The majority of the screen is taken up by the main focus:" or, even simpler, "The majority of the screen is taken up by the documentation text[...]".

GuillaumeGomez · 2021-11-01T21:50:12Z

src/doc/rustdoc/src/how-to-read-rustdoc.md

+The main title is the type and name of the item,
+such as "Struct `std::time::Duration`",
+along with a button to collapse or expand the top-level documentation for that
+item (`[+]` or `[-]`),


@jsha If we merge this PR with this doc, we'll need to not forget to update it in case we change the collapse/expand buttons.

Yep, makes sense! We would also need to update https://doc.rust-lang.org/std/#how-to-read-this-documentation.

GuillaumeGomez · 2021-11-01T21:51:28Z

src/doc/rustdoc/src/how-to-read-rustdoc.md

+
+Below this is the main documentation for the item,
+including a definition or function signature if appropriate,
+followed by a list of fields or variants for structs, unions, and enums.


Instead of listing the different types, wouldn't it be better to simply say "for rust types"?

Seems reasonable!

GuillaumeGomez · 2021-11-01T21:53:49Z

src/doc/rustdoc/src/how-to-read-rustdoc.md

+
+Typing in the search bar instantly searches the available documentation for
+the string entered, with a fuzzy matching algorithm that is tolerant of omitted
+letters but not extra ones.


If I look for "stringa" in the std docs, it returns String. So simply saying "is tolerant to a given amount of typos" or something along the line is fine I guess.

Great! Reduced verbosity.

GuillaumeGomez · 2021-11-01T21:54:32Z

src/doc/rustdoc/src/how-to-read-rustdoc.md

+By clicking an item, you will navigate to its particular documentation.
+
+There are two other modes, shown as tabs in the search results pane.
+"In Parameters" searches for the string in the types of parameters to functions,


It doesn't search when clicking on another tab, it's simply how they're classified.

Ah, important distinction to make. Thanks!

GuillaumeGomez · 2021-11-01T21:54:37Z

src/doc/rustdoc/src/how-to-read-rustdoc.md

+
+There are two other modes, shown as tabs in the search results pane.
+"In Parameters" searches for the string in the types of parameters to functions,
+and "In Return Types" searches in the return types of functions.


GuillaumeGomez · 2021-11-01T21:55:34Z

src/doc/rustdoc/src/how-to-read-rustdoc.md

+
+Pressing `S` while focused elsewhere on the page will move focus to the
+search bar, and pressing `?` shows a help screen with many shortcuts.
+Pressing `T` focuses the theme picker.


Maybe talk about the help popup to see the full list (the one appearing when clicking on the ? button or pressing the ? key).

Should I not include the full list here?

It's fine to keep them. Maybe add a note that they are listed directly in the help popup too.

GuillaumeGomez · 2021-11-01T21:56:59Z

So overall, it's really nice. I wonder: could we add screenshots to make it easier for readers to follow? Or would it be too difficult to keep it up-to-date? (cc @rust-lang/rustdoc)

NoraCodes · 2021-11-01T21:58:15Z

I considered that, but first of all it would make this page inaccessible, or at least it would be very verbose if we wanted to keep it accessible to people who can't see images for whatever reason - and, yeah, I suspect it would be quite annoying to keep up to date.

GuillaumeGomez · 2021-11-01T21:58:50Z

src/doc/rustdoc/src/how-to-read-rustdoc.md

+When typing in the search bar, you can prefix your search term with a type
+followed by a colon (such as `mod:`) to restrict the results to just that
+kind of item - one of `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`,
+or `const`.


There are actually other things that the search input supports. I'm working on fixing the search input, so better to keep this and not go into deeper explanations and instead mention that more possibilities are listed in the help popup.

camelid

The one concern I have with this guide is that it will fall out of date as we improve the UI. Hopefully we can try to keep it up to date. Let's just make sure that the guide doesn't have scope creep, which would make it harder to keep current :)

camelid · 2021-11-01T22:05:54Z

src/doc/rustdoc/src/how-to-read-rustdoc.md

+The main title is the type and name of the item,
+such as "Struct `std::time::Duration`",
+along with a button to collapse or expand the top-level documentation for that
+item (`[+]` or `[-]`),
+a link to the source code (`[src]`),
+if [configured](the-doc-attribute.html#html_no_source),
+and the version in which the item became stable,
+if it's a stable item in the standard library.


This sentence is long; maybe use bullet points instead?

Good call, done!

camelid · 2021-11-01T22:09:37Z

I wonder: could we add screenshots to make it easier for readers to follow? Or would it be too difficult to keep it up-to-date?

Yeah, I think it'd be too difficult to keep up-to-date. People can compare side-by-side with a docs page if they want. Also, like NoraCodes said, it'd not be as accessible.

camelid · 2021-11-01T22:11:21Z

The one concern I have with this guide is that it will fall out of date as we improve the UI.

A related thing we should keep in mind is that docs generated with older versions of rustdoc (e.g., many crates on docs.rs) won't match up to the description in the guide. (Side note: @jyn514 would it be feasible for docs.rs to regenerate docs, say once a year, for crates over a certain download rate even if they haven't been updated?)

jyn514 · 2021-11-01T23:13:41Z

. (Side note: @jyn514 would it be feasible for docs.rs to regenerate docs, say once a year, for crates over a certain download rate even if they haven't been updated?)

rust-lang/docs.rs#464

jyn514 · 2021-11-02T16:20:14Z

cc @pierwill

jyn514

This is great! Thank you for working on this :)

jyn514 · 2021-11-02T16:23:44Z

src/doc/rustdoc/src/how-to-read-rustdoc.md

+- a button to collapse or expand the top-level documentation for that item
+  (`[+]` or `[-]`),
+- a link to the source code (`[src]`),
+  if [configured](the-doc-attribute.html#html_no_source),


Suggested change

if [configured](the-doc-attribute.html#html_no_source),

if [configured](the-doc-attribute.html#html_no_source) and present. The source may not be available if the documentation was created with `cargo doc --no-deps`.

Hi @NoraCodes - did you see this comment? Was it intentional to not add this sentence?

Yeah, sorry! I thought there was a discussion about this but now I can't find it - did I hallucinate that? lol

Okay, yeah, still can't find it. I don't think we should mention this here because it's intended to be a guide for docs readers - we document --no-deps elsewhere.

Hmm, so the reason I thought to mention it was because it's pretty common for people to be confused by reading docs and having missing links. But I don't feel super strongly about it.

Yeah, sorry! I thought there was a discussion about this but now I can't find it - did I hallucinate that? lol

@NoraCodes I think you're thinking of #90487 (comment), which was a discussion about another command-line flag.

src/doc/rustdoc/src/how-to-read-rustdoc.md

jyn514 · 2021-11-02T16:28:15Z

src/doc/rustdoc/src/how-to-read-rustdoc.md

+Both are very useful when looking for a function whose name you can't quite
+bring to mind when you know the type you have or want.


It's also useful if you don't know whether the function exists, but you think it should (e.g. Option<T> -> T or String -> PathBuf).

Just noting that neither of those examples work as search queries currently. I assume you didn't mean using those as queries verbatim?

Sure it does:

https://doc.rust-lang.org/stable/std/path/struct.PathBuf.html#method.from-5

The results include functions that don't have String in their parameters (like Path::join). String -> PathBuf implies that it will show only functions that takes Strings and return PathBufs.

🤷‍♂️ I don't think there exist any useful type-based search queries for which rustdoc doesn't have bugs. I don't think we should block documenting how to use the feature on fixing the bugs.

Those aren't useful searches though. We should give an example of why you would want to use the feature.

What do you mean? String -> PathBuf isn't useful either, because it returns the same results as -> PathBuf. Personally, I think we should avoid documenting type-based search here until the dust settles a bit (since Guillaume is working on an overhaul of it right now). After Guillaume finishes his overhaul, IIUC String -> PathBuf should work correctly.

We should give an example of why you would want to use the feature.

Giving a broken example of why you'd want to use the feature seems worse than giving no example at all.

Yeah, I think we should wait on this until it's updated, if that's already in progress.

You can take a look here if you want to see what it looks like. ;)

(I opened the PR here).

Includes documentation for: - general page structure - navigation - searching - themes - deep-linking Doesn't include docs on the settings page.

NoraCodes · 2021-11-05T19:44:52Z

Okay, I believe I've addressed all PR feedback here.

GuillaumeGomez · 2021-11-05T20:00:25Z

Thanks! I'll review it tomorrow.

GuillaumeGomez

Looks good to me.

jyn514

Looks good to me other than one nit :) thanks for working on this!

jyn514 · 2021-11-06T16:38:29Z

src/doc/rustdoc/src/how-to-read-rustdoc.md

+- a button to collapse or expand the top-level documentation for that item
+  (`[+]` or `[-]`),
+- a link to the source code (`[src]`),
+  if [configured](the-doc-attribute.html#html_no_source),


Hi @NoraCodes - did you see this comment? Was it intentional to not add this sentence?

jyn514 · 2021-11-06T17:50:22Z

@bors r+ rollup

Thanks again!

bors · 2021-11-06T17:50:23Z

📌 Commit 768554a has been approved by jyn514

… r=jyn514 Add a chapter on reading Rustdoc output Includes documentation for: - general page structure - navigation - searching - themes - deep-linking Doesn't include docs on the settings page. Per rust-lang#90309

…askrgr Rollup of 6 pull requests Successful merges: - rust-lang#90487 (Add a chapter on reading Rustdoc output) - rust-lang#90508 (Apply adjustments for field expression even if inaccessible) - rust-lang#90627 (Suggest dereference of `Box` when inner type is expected) - rust-lang#90642 (use matches!() macro in more places) - rust-lang#90646 (type error go brrrrrrrr) - rust-lang#90649 (Run reveal_all on MIR when inlining is activated.) Failed merges: r? `@ghost` `@rustbot` modify labels: rollup

rust-highfive assigned GuillaumeGomez Nov 1, 2021

rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Nov 1, 2021

GuillaumeGomez reviewed Nov 1, 2021

View reviewed changes

jyn514 added the T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. label Nov 1, 2021

GuillaumeGomez reviewed Nov 1, 2021

View reviewed changes

This comment has been minimized.

Sign in to view

NoraCodes force-pushed the nora/how-to-read-rustdoc branch from cbfc498 to ecb8bfc Compare November 1, 2021 22:06

camelid reviewed Nov 1, 2021

View reviewed changes

NoraCodes force-pushed the nora/how-to-read-rustdoc branch from ecb8bfc to 913ec96 Compare November 2, 2021 15:57

This comment has been minimized.

Sign in to view

jyn514 reviewed Nov 2, 2021

View reviewed changes

Add a chapter on reading Rustdoc output

768554a

Includes documentation for: - general page structure - navigation - searching - themes - deep-linking Doesn't include docs on the settings page.

NoraCodes force-pushed the nora/how-to-read-rustdoc branch from 913ec96 to 768554a Compare November 5, 2021 19:44

GuillaumeGomez approved these changes Nov 6, 2021

View reviewed changes

jyn514 reviewed Nov 6, 2021

View reviewed changes

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Nov 6, 2021

This was referenced Nov 6, 2021

Rollup of 5 pull requests #90659

Closed

Rollup of 6 pull requests #90661

Merged

bors merged commit de332b5 into rust-lang:master Nov 7, 2021

rustbot added this to the 1.58.0 milestone Nov 7, 2021

jyn514 mentioned this pull request Nov 30, 2021

Add a rustdoc user guide to https://doc.rust-lang.org/rustdoc #90309

Closed


		## The Item Documentation

		The majority of the screen is taken up with the main event:

	if [configured](the-doc-attribute.html#html_no_source),
	if [configured](the-doc-attribute.html#html_no_source) and present. The source may not be available if the documentation was created with `cargo doc --no-deps`.

		Both are very useful when looking for a function whose name you can't quite
		bring to mind when you know the type you have or want.

Add a chapter on reading Rustdoc output #90487

Add a chapter on reading Rustdoc output #90487

Conversation

NoraCodes commented Nov 1, 2021

rust-highfive commented Nov 1, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

GuillaumeGomez commented Nov 1, 2021

NoraCodes commented Nov 1, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

This comment has been minimized.

camelid left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

camelid commented Nov 1, 2021

camelid commented Nov 1, 2021 • edited Loading

jyn514 commented Nov 1, 2021

This comment has been minimized.

jyn514 commented Nov 2, 2021

jyn514 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

camelid Nov 2, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

NoraCodes commented Nov 5, 2021 • edited Loading

GuillaumeGomez commented Nov 5, 2021

GuillaumeGomez left a comment

Choose a reason for hiding this comment

jyn514 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jyn514 commented Nov 6, 2021

bors commented Nov 6, 2021

camelid commented Nov 1, 2021 •

edited

Loading

camelid Nov 2, 2021 •

edited

Loading

NoraCodes commented Nov 5, 2021 •

edited

Loading