Make searches case-aware, and prefer case-exact matches (even in dependent packages) to case-inexact matches

[Hixie]

STEPS TO REPRODUCE

1. Open https://main-api.flutter.dev/
2. Click the search field in the top right, or press /.
3. Type Duration.
4. Press Enter.

EXPECTED RESULTS

The Duration class should be the top result after step 3 and in the complete list after step 4.

ACTUAL RESULTS

Duration doesn't appear anywhere.

The Duration class is in the API docs though: https://main-api.flutter.dev/flutter/dart-core/Duration-class.html

[Hixie]

cc @gspencergoog

[gspencergoog]

This is a weird one. I also notice that the Size class is similarly hidden in search. They both exist in the dart:core library listing, and in fact there seem to be references in the search results to the constructor for the class: In the case of Size, it has a hit from "The Size class" for the "Size" constructor.

[srawlins]

Why should Duration be the top result? Dartdoc currently prefers results in the main package being documented. Would you prefer it value all packages, including all dependencies, equally?

[gspencergoog]

It's not that it's not the top result, it's that it doesn't appear in the list at all, as far as I can see.

[gspencergoog]

Given how much it is used in the framework, it does seem like it should be on the first page of results at least, even if it's not the top result.

[srawlins]

It's not that it's not the top result, it's that it doesn't appear in the list at all, as far as I can see.

Correct, we only display the top 10 results, and there are at least 10 results in package:flutter. Pressing enter gets you the full results.

Given how much it is used in the framework, it does seem like it should be on the first page of results at least, even if it's not the top result.

If you can think of a generic criteria that would put it above elements in package:flutter, I can implement it.

[gspencergoog]

Ahh, OK. so it's not in the top ten results, but it does appear in the overall results if you hit enter, I see that now.

[srawlins]

Given how much it is used in the framework, it does seem like it should be on the first page of results at least

We don't have any metric of how "important" or how "used" an element is, and I think that would be a great improvement. Two metrics come to mind:

• How often a certain element is visited by users to api.flutter.dev. Very hard to do, haha.
• How often an element is referenced by other elements at api.flutter.dev. Not so hard! I think.

So if we wanted to implemente such a system, it would just take some time, and need to be staffed and prioritized and staffed.

[gspencergoog]

So if we wanted to implement such a system, it would just take some time, and need to be staffed and prioritized and staffed.

And staffed. :-)

[Hixie]

Oh wow, I had no idea it did appear in the actual results. It's so buried. I really expected it to be the top result.

If I search for Duration and there's a class called Duration, it's very confusing to me that Duration isn't the top result.

[srawlins]

The search prioritizes results from dependency packages depending on the --package-order given at the time of dartdoc-generation. Currently Flutter's script puts Flutter first and Dart second, and other things later, I guess. It doesn't look like there is a way to consider two packages on equal footing.

We could add a syntax like a+b to indicate packages a and b should be considered as having the same package rank. So Flutter might use --package-order=Flutter+Dart,$kPlatformIntegrationPackageName,flutter_test+flutter_driver.

[gspencergoog]

You know, I wonder if just making it more case sensitive would help. I expect to see "Duration" if I type "Duration", but if I type "duration" I might expect to see either.

[Hixie]

I think it's also weird that if I type Duratio then Durations comes up as a possible match, but if I add a letter that continues to match (to wit, Duration), then suddenly Durations stops matching, even though surely if Durations was a good match for Duratio it's an even better match for Duration.

[srawlins]

This is intentional and important. If a search (duration) matches multiple suggestions, the very very first ones are the exact matches. This is because it is impossible for the user to type anything further in order to get closer to their target, if their target is an exact match (like duration under DrawerHeader). If all of the possible suggestions are substrings though (such as Durations, and duration under DrawerHeader for the search duratio), then we just sort by the regular priority sorts. In this case, Durations as a class trumps any duration properties.

It sounds like the cause of a lot of surprises is the 10-element limit. We could increase that, or make it a scrollable space that takes up the height of 10 elements.

[Hixie]

Well that's fine but Duration is an even better match so... that's why I expect to see that. :-)

[srawlins]

Well that's fine but Duration is an even better match so... that's why I expect to see that. :-)

Why should Duration be the top result?

If you can think of a generic criteria that would put it above elements in package:flutter, I can implement it.

[Hixie]

Make the search case-aware, and score case-exact matches higher than case-inexact ones.

[Hixie]

I guess another way would be to score class matches higher than member matches. I would rarely, if ever, type "duration" and expect to get AnimationController.duration as opposed to Duration. If I wanted AnimationController.duration I would type AnimationController.duration. Especially because there are so many durations that there's no way I would ever expect the one I cared about to be at the top. On the other hand, since Duration is the entire fully qualified name of the class, I couldn't give any more specific a name, so it seems like it would be good to see it at the top.

Indeed by that reasoning I'd probably expect to see Durations above the properties more as well. Maybe a way to implement that would be to consider the fully qualified name when considering how far away the current search input is from the various targets, instead of just the member's name.

[justinmc]

+1 to Hixie's last comment, classes should sort higher than members. I pointed out a similar problem in flutter/website#10369.

I swear this used to work and is a recent regression. The search code looks like it is trying to do this:

dartdoc/lib/src/search.dart

Lines 75 to 79 in f339b09

	// Prefer top-level elements to library members to class (etc.) members.
	comparison = a.item._scope - b.item._scope;
	if (comparison != 0) {
	return comparison;
	}

[Hixie]

I think this is P1, not P3. This is by far the biggest problem I run into when using our docs now. It's literally causing documentation to be hidden. I just tried to look up the Rect class for example and it wasn't even in the dropdown for rect or Rect.