Add ?doc command

[jcdyer]

I'd love to be able to use ferris to link to API documentation. I propose a new command ?doc path::to::item, which will provide a link to the named item. If path::to::item matches ^(std|core|alloc)(::|$), then it should return a link to the appropriate documentation page on https://doc.rust-lang.org, otherwise it should link to the appropriate documentation page on docs.rs.

I do not envision linking to search pages, fuzzy matching, or any other sort of guessing. If the user doesn't provide an exact match, ferris should respond with a friendly error message.

Examples:

User: ?doc core::option::Option
Ferris: https://doc.rust-lang.org/core/option/enum.Option.html
User: ?doc serde::Deserialize
Ferris: https://docs.rs/serde/latest/serde/trait.Deserialize.html
User: ?doc serde::Deser
Ferris: Could not find a page matching serde::Deser

Note: docs.rs links generally have a version number in them, but /latest/ redirects to the current version, so we can use that.

[jcdyer]

I'm happy to implement this, but wanted to kick the tires before I get started, see if anyone has opinions about how it should work.

[kangalio]

Would ?doc serde just like that work too? If yes, #4's crate commands can be dismissed in favor of this proposal

[jyn514]

I'm curious why you want to avoid search. If you're ok with search this would be easy to do by linking to https://docs.rs/serde/latest/?search=serde::Deserialize. Otherwise it will be very hard because you have to know what type Deserialize is.

[jcdyer]

@kangalioo It seems ?doc serde should be easy to implement.

@jyn514 Linking the search page seems a little less useful, and a lot less friendly to the recipient. It's like saying "let me google that for you" instead of providing a link to a page with real information. Personally, I wouldn't use a ?doc command that returned a search page, because it feels rude.

[jcdyer]

And it turns out the module page has very nicely tagged links for each item in the module, so it will require two queries instead of one, but wouldn't require any guessing as to what kind of object you're looking for.

<tr class="module-item">
  <td>
    <a class="trait" href="trait.Error.html" title="serde::de::Error trait">Error</a>
  </td>
  <td class="docblock-short">
    <p>The <code>Error</code> trait allows <code>Deserialize</code> implementations to create descriptive error messages belonging to the <code>Deserializer</code> against which they are
currently running.</p>
  </td>
</tr>

• ?doc serde -> Known URL just fetch it.
• ?doc serde::de -> de could be any type: fetch module page for serde, and find link to de as a module.
• ?doc serde::de::Error -> error could be any type, but de is a module. Fetch the module page for serde::de, and search it for the link to enum.Error.html.

[jcdyer]

Hmm. This doesn't account for elements below item level.

• ?doc serde::de::Visitor::visit_bool would be hard to find.

[jyn514]

And more than that, you don't know if Visitor is an item or a module. So you don't know whether to look at struct.Visitor.html or Visitor/index.html. You'd have to look up each segment in the namespace one page at a time.

[kangalio]

Is there any reason against querying the search result page and presenting the first search result link to the user? This will require just one network request and have all the advantages of the search functionality

[jcdyer]

Is there any reason against querying the search result page and presenting the first search result link to the user? This will require just one network request and have all the advantages of the search functionality

That would probably work.

[kangalio]

Actually, that won't work like that because rustdoc seems to rely heavily on dynamic html creation using javascript, hence the search result data is not actually available from the html.

What the official Rust bot does here is, it just simply links to the search results page. It's a bit unfortunate because then the Discord preview doesn't show the actual item docs, and to access the docs you have to click twice. But it's better than nothing.

What do you think about linking to the search results page?

[jyn514]

Actually, that won't work like that because rustdoc seems to rely heavily on dynamic html creation using javascript, hence the search result data is not actually available from the html.

For context, this because search has to work when viewing file:/// URLs, without a webserver present. So it's not possible to generate the HTML ahead of time, it has to be done with javascript.