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

Add ability to search by type signature on the docs #658

Closed
steveklabnik opened this Issue Jan 21, 2015 · 9 comments

Comments

Projects
None yet
3 participants
@steveklabnik
Copy link
Member

steveklabnik commented Jan 21, 2015

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

This comment has been minimized.

Copy link

mihneadb commented Feb 27, 2015

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.

screenshot from 2015-02-28 00 54 00

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

This comment has been minimized.

Copy link

mihneadb commented Mar 4, 2015

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

@mihneadb

This comment has been minimized.

Copy link

mihneadb commented Mar 8, 2015

@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

This comment has been minimized.

Copy link
Member

steveklabnik commented Mar 11, 2015

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

@steveklabnik

This comment has been minimized.

Copy link
Member

steveklabnik commented Mar 11, 2015

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.

@Gankro

This comment has been minimized.

Copy link
Contributor

Gankro commented Mar 11, 2015

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

@mihneadb

This comment has been minimized.

Copy link

mihneadb commented Mar 12, 2015

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

bors added a commit to rust-lang/rust that referenced this issue Mar 14, 2015

Auto merge of #23289 - mihneadb:rustdoc-search-by-type, r=alexcrichton
This adds search by type (for functions/methods) support to Rustdoc. Target issue is at rust-lang/rfcs#658.

I've described my approach here: rust-lang/rfcs#658 (comment). I'll copy the text in here as well:

---

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](#12866 (comment))).

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:

```rust
fn to_uppercase(c: char) -> char
```

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

Method (implemented or defined in trait):

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

```json
{
    "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 master...mihneadb:rustdoc-search-by-type. You can check out a live demo [here](http://data.mihneadb.net/doc/std/index.html?search=charext%20-%3E%20char).

![screenshot from 2015-02-28 00 54 00](https://cloud.githubusercontent.com/assets/643127/6422722/7e5374ee-bee4-11e4-99a6-9aac3c9d5068.png)


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 -> `](http://data.mihneadb.net/doc/std/index.html?search=vec%2C%20t%20-%3E))
- 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)?

---

Manishearth added a commit to Manishearth/rust that referenced this issue Mar 14, 2015

Rollup merge of rust-lang#23289 - mihneadb:rustdoc-search-by-type, r=…
…alexcrichton

 This adds search by type (for functions/methods) support to Rustdoc. Target issue is at rust-lang/rfcs#658.

I've described my approach here: rust-lang/rfcs#658 (comment). I'll copy the text in here as well:

---

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](rust-lang#12866 (comment))).

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:

```rust
fn to_uppercase(c: char) -> char
```

```json
{
    \"inputs\": [
        {\"name\": \"char\"}
    ],
    \"output\": {
        \"name\": \"char\",
    }
}
```

Method (implemented or defined in trait):

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

```json
{
    \"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](http://data.mihneadb.net/doc/std/index.html?search=charext%20-%3E%20char).

![screenshot from 2015-02-28 00 54 00](https://cloud.githubusercontent.com/assets/643127/6422722/7e5374ee-bee4-11e4-99a6-9aac3c9d5068.png)

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 -> `](http://data.mihneadb.net/doc/std/index.html?search=vec%2C%20t%20-%3E))
- 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

This comment has been minimized.

Copy link

mihneadb commented Mar 16, 2015

@steveklabnik I think this issue can be closed.

@steveklabnik

This comment has been minimized.

Copy link
Member

steveklabnik commented Mar 16, 2015

woot!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment