Add ability to search by type signature on the docs

[steveklabnik]

Issue by reem
Thursday Mar 13, 2014 at 16:49 GMT

For earlier discussion, see rust-lang/rust#12866

This issue was labelled with: A-an-interesting-project, A-rustdoc, E-hard in the Rust repository

---

One of hoogle's most useful features is the ability to search by type signatures. It makes finding functions whose behavior you know but whose names you don't know much easier.

We should add this ability to the search feature in the rust docs.

[mihneadb]

Hi, it took me longer than I wished, but I have implemented this in a not-too-complex way that I think can be extended to support more complex features (like the ones mentioned here).

The idea is to generate a JSON representation of the types of methods/functions in the existing index, and then make the JS understand when it should look by type (and not by name).

I tried to come up with a JSON representation that can be extended to support generics, bounds, ref/mut annotations and so on. Here are a few samples:

Function:

fn to_uppercase(c: char) -> char

{
    "inputs": [
        {"name": "char"}
    ],
    "output": {
        "name": "char",
    }
}

Method (implemented or defined in trait):

// in struct Vec
// self is considered an argument as well
fn capacity(&self) -> usize

{
    "inputs": [
        {"name": "vec"}
    ],
    "output": {
        "name": "usize"
    }
}

This simple format can be extended by adding more fields, like generic: bool, a bounds mapping and so on.

I have a working implementation in rust-lang/rust@master...mihneadb:rustdoc-search-by-type. You can check out a live demo here.

The feature list is not that long:

• search by types (you can use generics as well, as long as you use the exact name - e.g. vec,t ->)
• order of arguments does not matter
• self is took into account as well (e.g. search for vec -> usize)
• does not use "complex" annotations (e.g. you don't search for &char -> char but for char -> char)

My goal is to get a working, minimal "base" merged so that others can build upon it. How should I proceed? Do I open a PR (badly in need of code review since this is my first non "hello world"-ish rust code)?

[mihneadb]

@steveklabnik could you please help me find someone to help me pursue checking this in? :) Thanks!

[mihneadb]

@huonw I know you were interested in the original issue. Can you help me with next steps to continue, please? My confusion starts with the fact that this issue is now in the rfcs repo, although I am not proposing any additions to the language itself.
Thanks!

[steveklabnik]

One akward thing is that nobody really 'owns' Rustdoc. This scheme looks pretty legit to me.

[steveklabnik]

My confusion starts with the fact that this issue is now in the rfcs repo, although I am not proposing any additions to the language itself.

So, we're now collecting any feature-request style things in the repo. The whole "rust distribution." While Rustdoc might not be the language, this will affect every single Rust crate.

[Gankra]

@alexcrichton and @tomjakubowski are the closest things to owners of rustdoc I know of

[mihneadb]

Thanks @gankro, @alexcrichton has assigned himself for reviewing the PR.

[mihneadb]

@steveklabnik I think this issue can be closed.

[steveklabnik]

woot!