Improve searching in rustdoc and add tests #64094

ayuusweetfish · 2019-09-02T13:19:53Z

👋 I have made searching in rustdoc more intuitive, added a couple more tests and made a little shell script to aid testing. Closes #63005.

It took me quite a while to figure out how to run the tests for rustdoc (instead of running tests for other crates with rustdoc); the only pointer I found was hidden in the rustc book. Maybe this could be better documented? I shall be delighted to help if it is desirable.

jonas-schievink · 2019-09-02T13:40:20Z

r? @GuillaumeGomez

GuillaumeGomez · 2019-09-02T13:49:10Z

src/test/rustdoc-js-std/vec-new.js

@@ -3,6 +3,8 @@ const QUERY = 'Vec::new';
 const EXPECTED = {
    'others': [
        { 'path': 'std::vec::Vec', 'name': 'new' },
+        { 'path': 'std::rc::Rc', 'name': 'new' },


This is less good result. We specified Vec explicitly in here after all.

GuillaumeGomez · 2019-09-02T13:51:22Z

src/tools/rustdoc-js/tester.sh

@@ -0,0 +1,19 @@
+#!/bin/bash


I don't really understand the point of this little script (even with your explanations). You can already do it using the x.py script (which could be better documented I guess).

GuillaumeGomez · 2019-09-02T13:52:19Z

Thanks for the PR! Could you describe a bit more what you're trying to achieve in here? A test seemed like having less good results so I just want to be sure to fully understand what you have in mind with this PR.

ayuusweetfish · 2019-09-02T14:47:16Z

Ah sure. I intended to prioritize methods with the same name (final word). This could be helpful in that it would be possible get accurate results even if we only remember the last word (#59287 shows such a use case). If we want to know about methods in a particular type or module, we can always go to its own page instead.

It was my carelessness to have missed the x.py test command, my apologies (^ ^;) I am trying that right now, but the --keep-stage flag somehow breaks here. Do I need to rebuild without it?

$ RUST_BACKTRACE=1 ./x.py test src/test/rustdoc-js --keep-stage 1
Updating only changed submodules
Submodules updated in 0.06 seconds
    Finished dev [unoptimized] target(s) in 0.13s
Building stage0 std artifacts (x86_64-apple-darwin -> x86_64-apple-darwin)
    Finished release [optimized] target(s) in 0.20s
Copying stage0 std from stage0 (x86_64-apple-darwin -> x86_64-apple-darwin / x86_64-apple-darwin)
Building stage0 compiler artifacts (x86_64-apple-darwin -> x86_64-apple-darwin)
    Finished release [optimized] target(s) in 0.21s
Copying stage0 rustc from stage0 (x86_64-apple-darwin -> x86_64-apple-darwin / x86_64-apple-darwin)
Building stage0 codegen artifacts (x86_64-apple-darwin -> x86_64-apple-darwin, llvm)
    Finished release [optimized] target(s) in 0.22s
Assembling stage1 compiler (x86_64-apple-darwin)
Warning: Using a potentially old libstd. This may not behave well.
Copying stage1 std from stage1 (x86_64-apple-darwin -> x86_64-apple-darwin / x86_64-apple-darwin)
Warning: Using a potentially old librustc. This may not behave well.
Copying stage1 rustc from stage1 (x86_64-apple-darwin -> x86_64-apple-darwin / x86_64-apple-darwin)
thread 'main' panicked at 'fs::read(stamp) failed with No such file or directory (os error 2)', src/bootstrap/lib.rs:1129:24
stack backtrace:
   0: backtrace::backtrace::libunwind::trace
             at /Users/vsts/.cargo/registry/src/github.com-1ecc6299db9ec823/backtrace-0.3.34/src/backtrace/libunwind.rs:88
   1: backtrace::backtrace::trace_unsynchronized
             at /Users/vsts/.cargo/registry/src/github.com-1ecc6299db9ec823/backtrace-0.3.34/src/backtrace/mod.rs:66
   2: std::sys_common::backtrace::_print
             at src/libstd/sys_common/backtrace.rs:47
   3: std::sys_common::backtrace::print
             at src/libstd/sys_common/backtrace.rs:36
   4: std::panicking::default_hook::{{closure}}
             at src/libstd/panicking.rs:200
   5: std::panicking::default_hook
             at src/libstd/panicking.rs:214
   6: std::panicking::rust_panic_with_hook
             at src/libstd/panicking.rs:477
   7: std::panicking::continue_panic_fmt
             at src/libstd/panicking.rs:384
   8: std::panicking::begin_panic_fmt
             at src/libstd/panicking.rs:339
   9: bootstrap::Build::read_stamp_file
             at src/bootstrap/lib.rs:1129
  10: bootstrap::compile::add_to_sysroot
             at src/bootstrap/compile.rs:941
  11: <bootstrap::compile::RustcLink as bootstrap::builder::Step>::run
             at src/bootstrap/compile.rs:509
  12: bootstrap::builder::Builder::ensure
             at src/bootstrap/builder.rs:1238
  13: <bootstrap::compile::Rustc as bootstrap::builder::Step>::run
             at src/bootstrap/compile.rs:396
  14: bootstrap::builder::Builder::ensure
             at src/bootstrap/builder.rs:1238
  15: <bootstrap::compile::Assemble as bootstrap::builder::Step>::run
             at src/bootstrap/compile.rs:871
  16: bootstrap::builder::Builder::ensure
             at src/bootstrap/builder.rs:1238
  17: bootstrap::builder::Builder::compiler
             at src/bootstrap/builder.rs:564
  18: <bootstrap::test::RustdocJSNotStd as bootstrap::builder::Step>::make_run
             at src/bootstrap/test.rs:696
  19: bootstrap::builder::StepDescription::maybe_run
             at src/bootstrap/builder.rs:183
  20: bootstrap::builder::StepDescription::run
             at src/bootstrap/builder.rs:226
  21: bootstrap::builder::Builder::run_step_descriptions
             at src/bootstrap/builder.rs:556
  22: bootstrap::builder::Builder::execute_cli
             at src/bootstrap/builder.rs:546
  23: bootstrap::Build::build
             at src/bootstrap/lib.rs:449
  24: bootstrap::main
             at src/bootstrap/bin/main.rs:15
  25: std::rt::lang_start::{{closure}}
             at /rustc/e450539c2a8d7f791268d699cbe45ab3e57d43a1/src/libstd/rt.rs:64
  26: std::rt::lang_start_internal::{{closure}}
             at src/libstd/rt.rs:49
  27: std::panicking::try::do_call
             at src/libstd/panicking.rs:296
  28: __rust_maybe_catch_panic
             at src/libpanic_unwind/lib.rs:80
  29: std::panicking::try
             at src/libstd/panicking.rs:275
  30: std::panic::catch_unwind
             at src/libstd/panic.rs:394
  31: std::rt::lang_start_internal
             at src/libstd/rt.rs:48
  32: std::rt::lang_start
             at /rustc/e450539c2a8d7f791268d699cbe45ab3e57d43a1/src/libstd/rt.rs:64
  33: bootstrap::main

GuillaumeGomez · 2019-09-02T18:09:45Z

Ah sure. I intended to prioritize methods with the same name (final word). This could be helpful in that it would be possible get accurate results even if we only remember the last word (#59287 shows such a use case). If we want to know about methods in a particular type or module, we can always go to its own page instead.

I don't really agree with this: if you specified the parent item (so vec in vec::new), vec elements shouldn't be lower, on the contrary.

On another case, if you're looking for a type and you make a typo, you want both the type and the method to be somewhat at the same level, not all methods then the type (based on the fact that they have the same levenhstein level result).

It was my carelessness to have missed the x.py test command, my apologies (^ ^;) I am trying that right now, but the --keep-stage flag somehow breaks here. Do I need to rebuild without it?

No worries, x.py isn't easy to get started with (I was lucky to see it evolving so that made learning using it way easier hehe). Otherwise, I actually never used the --keep-stage flag... I usually run with --stage 1 and that's pretty much it.

ayuusweetfish · 2019-09-03T08:52:31Z

Previously x.py filtered out all tests in rustdoc-js; I have pushed a fix and now ./x.py test src/test/rustdoc-js --stage 1 works normally. Please kindly point out if anything can be done in better ways!

As for results ordering, we can keep only the most intuitive requirements in tests and get rid of others, but I'd like to insist on this implementation. (tl;dr ends here 😝)

if you're looking for a type and you make a typo, you want both the type and the method to be somewhat at the same level, not all methods then the type

I think it's usually easy for the user to fix the typo themself, and it should be fine as long as we are returning meaningful results.

When we type Vec::new correctly, how other results are ordered is actually irrelevant. However, prioritizing final word equivalence is particularly helpful for short names. Also, the current calculation does not simply take the actual Levenshtein distance, but a rounded average over namespaces plus minor adjustments instead. This value may be biased in corner cases and can disarrange the results if used as a primary keyword.

Many other documentation sites are doing it this way as well: Hoogle (List.init), cppreference.com (vector::size).

GuillaumeGomez · 2019-09-04T08:27:29Z

You should send a new PR for the x.py fix. Not a good idea to mix too much things.

Otherwise, I still have issues to see how these changes improve the search... Normally, exact matches are put up by adding a small advantage. Or did I miss something?

ayuusweetfish · 2019-09-04T08:33:17Z

Okay, I shall separate the x.py fix.

This mainly aims at two use cases that current nightly does not handle well:

Very short names (rustdoc search should ensure it shows exact matches #59287, regression)
Exact matches (rustdoc: Searching for path (including a ::) does not work #63005)

Edit: relevant logic ↓

rust/src/librustdoc/html/static/main.js

Lines 1102 to 1106 in b9de4ef

    
           } else if (searchWords[j] === val) { 
        
               // Small trick to fix when you're looking for a one letter type 
        
               // and there are other short named types. 
        
               lev = -1; 
        
           }

This advantage is by no means small, and overwrites the Levenshtein biases completely.

rust/src/librustdoc/html/static/main.js

Lines 561 to 564 in b9de4ef

    
           // sort by exact match (mismatch goes later) 
        
           a = (aaa.word !== valLower); 
        
           b = (bbb.word !== valLower); 
        
           if (a !== b) { return a - b; }

These have no effect in many cases, because valLower is the path (vec::new) but aaa.word is only the last word (new).

I should have explained it earlier, sorry for the confusion ._.

ayuusweetfish · 2019-09-04T08:47:02Z

Is it better now?

GuillaumeGomez · 2019-09-04T13:13:32Z

Yes, I prefer the current result. Can you squash your commits please? Once done, I'll approve the PR.

ayuusweetfish · 2019-09-04T13:22:19Z

Accidentally messed up, fixing 😓

ayuusweetfish · 2019-09-04T13:29:03Z

I think it's ready now!

GuillaumeGomez

👍

GuillaumeGomez · 2019-09-04T16:32:04Z

Thanks!

@bors: r+ rollup

bors · 2019-09-04T16:32:05Z

📌 Commit cb84aa4 has been approved by GuillaumeGomez

…umeGomez Improve searching in rustdoc and add tests 👋 I have made searching in rustdoc more intuitive, added a couple more tests and made a little shell script to aid testing. Closes rust-lang#63005. It took me quite a while to figure out how to run the tests for rustdoc (instead of running tests for other crates with rustdoc); the only pointer I found was [hidden in the rustc book](https://rust-lang.github.io/rustc-guide/rustdoc.html#cheat-sheet). Maybe this could be better documented? I shall be delighted to help if it is desirable.

@ghost

Rollup of 5 pull requests Successful merges: - #63676 (Use wasi crate for Core API) - #64094 (Improve searching in rustdoc and add tests) - #64111 (or-patterns: Uniformly use `PatKind::Or` in AST & Fix/Cleanup resolve) - #64156 (Assume non-git LLVM is fresh if the stamp file exists) - #64175 (Fix invalid span generation when it should be div) Failed merges: - #63806 (Upgrade rand to 0.7) r? @ghost

…umeGomez Improve searching in rustdoc and add tests 👋 I have made searching in rustdoc more intuitive, added a couple more tests and made a little shell script to aid testing. Closes rust-lang#63005. It took me quite a while to figure out how to run the tests for rustdoc (instead of running tests for other crates with rustdoc); the only pointer I found was [hidden in the rustc book](https://rust-lang.github.io/rustc-guide/rustdoc.html#cheat-sheet). Maybe this could be better documented? I shall be delighted to help if it is desirable.

@ghost

Rollup of 10 pull requests Successful merges: - #63676 (Use wasi crate for Core API) - #64094 (Improve searching in rustdoc and add tests) - #64111 (or-patterns: Uniformly use `PatKind::Or` in AST & Fix/Cleanup resolve) - #64156 (Assume non-git LLVM is fresh if the stamp file exists) - #64161 (Point at variant on pattern field count mismatch) - #64174 (Add missing code examples on Iterator trait) - #64175 (Fix invalid span generation when it should be div) - #64186 (std: Improve downstream codegen in `Command::env`) - #64190 (fill metadata in rustc_lexer's Cargo.toml) - #64198 (Add Fuchsia to actually_monotonic) Failed merges: r? @ghost

rust-highfive assigned nikomatsakis Sep 2, 2019

ayuusweetfish mentioned this pull request Sep 2, 2019

rustdoc: Searching for path (including a ::) does not work #63005

Closed

rust-highfive assigned GuillaumeGomez and unassigned nikomatsakis Sep 2, 2019

GuillaumeGomez reviewed Sep 2, 2019

View reviewed changes

ayuusweetfish force-pushed the rustdoc-search branch from dd2de55 to 285650a Compare September 4, 2019 13:18

ayuusweetfish force-pushed the rustdoc-search branch from 285650a to 3f37938 Compare September 4, 2019 13:26

Improve searching in rustdoc and add tests

cb84aa4

ayuusweetfish force-pushed the rustdoc-search branch from 3f37938 to cb84aa4 Compare September 4, 2019 13:27

ayuusweetfish changed the title ~~Improve searching in rustdoc; tests included~~ Improve searching in rustdoc and add tests Sep 4, 2019

GuillaumeGomez approved these changes Sep 4, 2019

View reviewed changes

bors added the S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. label Sep 4, 2019

Centril mentioned this pull request Sep 5, 2019

Rollup of 7 pull requests #64181

Closed

Centril mentioned this pull request Sep 5, 2019

Rollup of 5 pull requests #64182

Closed

Mark-Simulacrum mentioned this pull request Sep 6, 2019

Rollup of 13 pull requests #64200

Closed

Centril mentioned this pull request Sep 6, 2019

Rollup of 10 pull requests #64209

Merged

bors merged commit cb84aa4 into rust-lang:master Sep 6, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve searching in rustdoc and add tests #64094

Improve searching in rustdoc and add tests #64094

ayuusweetfish commented Sep 2, 2019

jonas-schievink commented Sep 2, 2019

GuillaumeGomez Sep 2, 2019

GuillaumeGomez Sep 2, 2019

GuillaumeGomez commented Sep 2, 2019

ayuusweetfish commented Sep 2, 2019

GuillaumeGomez commented Sep 2, 2019

ayuusweetfish commented Sep 3, 2019

GuillaumeGomez commented Sep 4, 2019

ayuusweetfish commented Sep 4, 2019 •

edited

Loading

ayuusweetfish commented Sep 4, 2019

GuillaumeGomez commented Sep 4, 2019

ayuusweetfish commented Sep 4, 2019

ayuusweetfish commented Sep 4, 2019

GuillaumeGomez left a comment

GuillaumeGomez commented Sep 4, 2019

bors commented Sep 4, 2019

Improve searching in rustdoc and add tests #64094

Improve searching in rustdoc and add tests #64094

Conversation

ayuusweetfish commented Sep 2, 2019

jonas-schievink commented Sep 2, 2019

GuillaumeGomez Sep 2, 2019

Choose a reason for hiding this comment

GuillaumeGomez Sep 2, 2019

Choose a reason for hiding this comment

GuillaumeGomez commented Sep 2, 2019

ayuusweetfish commented Sep 2, 2019

GuillaumeGomez commented Sep 2, 2019

ayuusweetfish commented Sep 3, 2019

GuillaumeGomez commented Sep 4, 2019

ayuusweetfish commented Sep 4, 2019 • edited Loading

ayuusweetfish commented Sep 4, 2019

GuillaumeGomez commented Sep 4, 2019

ayuusweetfish commented Sep 4, 2019

ayuusweetfish commented Sep 4, 2019

GuillaumeGomez left a comment

Choose a reason for hiding this comment

GuillaumeGomez commented Sep 4, 2019

bors commented Sep 4, 2019

ayuusweetfish commented Sep 4, 2019 •

edited

Loading