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

rustdoc: improve web search snippets #82283

Closed
jsha opened this issue Feb 19, 2021 · 3 comments
Closed

rustdoc: improve web search snippets #82283

jsha opened this issue Feb 19, 2021 · 3 comments
Labels
A-rustdoc-ui Area: Rustdoc UI (generated HTML) C-enhancement Category: An issue proposing an enhancement or a PR with one. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.

Comments

@jsha
Copy link
Contributor

jsha commented Feb 19, 2021

Boilerplate

Some (but not all) search result snippets for rust items include the boilerplate "1.0.0[−][src]". Example screenshots below are linked to the Google search results page they are taken from.

Search results for "rust slice" show the boilerplate:
image

Search results for "rust slice" omit the boilerplate:
image

Per https://developers.google.com/search/docs/advanced/appearance/good-titles-snippets and https://developers.google.com/search/docs/advanced/crawling/special-tags#data-nosnippet, we can wrap this particular piece of boilerplate in <span data-nosnippet> to omit it from snippets.

Low-information meta descriptions

Also, search engines commonly make snippets from the <meta name="description" value="..."> tag. The tag rustdoc currently generates is very low-information. For instance:

API documentation for the Rust slice mod in crate std

API documentation for the Rust Error trait in crate std.

It would be much better to fill this tag with the first sentence (or two) of actual documentation. For instance:

A dynamically-sized view into a contiguous sequence, [T]. Slices are a view into a block of memory represented as a pointer and a length.

Error is a trait representing the basic expectations for error values, i.e., values of type E in Result<T, E>.

@jyn514
Copy link
Member

jyn514 commented Feb 19, 2021

It would be much better to fill this tag with the first sentence (or two) of actual documentation.

Rustdoc already does this for searches, it can use the same summaries for the description.

@jyn514 jyn514 added A-rustdoc-ui Area: Rustdoc UI (generated HTML) T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. C-enhancement Category: An issue proposing an enhancement or a PR with one. labels Feb 19, 2021
JohnTitor added a commit to JohnTitor/rust that referenced this issue Feb 22, 2021
…jyn514

Use the first paragraph, instead of cookie-cutter text, for rustdoc descriptions

Partially addresses rust-lang#82283.
@bors bors closed this as completed in 5538528 Feb 22, 2021
@jyn514
Copy link
Member

jyn514 commented Feb 22, 2021

This shouldn't have been closed, sorry, #82351 only addressed the "low information" part of the issue, not the "boilerplate" part.

@jyn514 jyn514 reopened this Feb 22, 2021
@jsha
Copy link
Contributor Author

jsha commented May 17, 2021

I think Google must have rolled out some changes to their snippet algorithm. I can no longer reproduce the issue of snippets showing the [-][src] boilerplate. Closing.

@jsha jsha closed this as completed May 17, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-rustdoc-ui Area: Rustdoc UI (generated HTML) C-enhancement Category: An issue proposing an enhancement or a PR with one. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
None yet
Development

No branches or pull requests

3 participants