rustdoc book: document sorting of search results

[lolbinarycat]

currently, the sorting of search results is a bit of a black box. we should add a subsection in the rustdoc book about how the sorting works.

based on this comment.

[notriddle]

There are three reasons why I hesitate to do this.

1. The more docs we write, the more we have to keep up-to-date. Incorrect docs are worse than incomplete docs.

2. Ranking is essentially guesswork. Other than the commonsense¹ rule that exact matches should appear first, we have to assume that the user knows roughly, but not exactly, what they're looking for.

3. Ranking is zero-sum. We can't make it easier to find anything without, by definition, making it harder to find something else.

Footnotes

1. this is not true if you're trying to filter out spam, but rustdoc doesn't have to deal with that ↩

[lolbinarycat]

hmm... all of these are valid points.

[hkBst]

Maybe document that? Exact results first, other results based on some scoring system (I am guessing) which is subject to change.

Though I can't help but think about evaluating the scoring system, that is, what makes it good/acceptable/workable.

[xizheyin]

Some structures have very many and complex methods, such as this, is it possible to search by description?

[hkBst]

@xizheyin if you're on the page you can use your browser's in-page search, but I'm sure that's not what you mean. Can you explain a little more what you do mean?

[lolbinarycat]

@xizheyin full text search is not supported, no.

you can however, use a regular search engine with a site: filter.

you may also be interested in type-based search, which is helpful for seeing how various types are constructed and retrieved.

[xizheyin]

@hkBst I meant pretty much what @lolbinarycat said, which probably means searching for features as described in the API. Searching by using a regular search engine is a good idea!

By the way,
I have another question. Is it possible to allow users/developers to contribute use cases or explanations to the documentation on the documentation's website (with the developer reviewing and presenting them), which would be easier than writing the documentation in code and submitting PR. Especially for heavily used libraries, the base of users is much larger than the developers.

I can start a separate issue if that makes sense.

[notriddle]

Rustdoc is a static site generator. User-contributed notes like php.net can't be done with this architecture.

Theoretically, docs.rs could do it, but they do not have the bandwidth to protect a public platform from spam.

Details

Having the crate author review user-contributed notes helps with bad suggestions posted by humans, but bot spam can only be dealt with automatically, and only the platform owner can do that. Only the platform owner can see your IP address, force you to solve a CAPTCHA, or fingerprint your browser / interaction timing. Without any of this stuff, the poor volunteer crate author is outnumbered.

Platforms like Reddit and GitHub have volunteer mods as a complement to automated bot blocking, not an alternative.

[xizheyin]

I get it, thanks for the explanation!