Search Relevance Tweaks

[shmax]

Search Terms

Search, Relevance, Lunr

Problem

My colleagues and I have spent the last few weeks rigging up TypeDoc on our TypeScript library. For the most part it works beautifully and we're astonished how well this project works out of the box, but we've been having some trouble with a few quirks in the search feature:

• exact matches don't seem to get a boost in relevance. We have a class called "Button", but when we search for "button", the main result we're interested in gets muscled down to the 53rd slot by other minor results that have "button" in their name (eg. "Foo.primaryButton"),
• there's no way to adjust the number of search results, and no "View all" option
• classes don't seem to get a boost over props and other minor features
• there's no way to boost on things like categories

I understand that not everyone wants search to work the same way, so I thought this might be a good candidate for a plugin, but once I looked into it I realized that plugins seem to have more to do with reflection than runtime adjustments like this.

So, before we dive in and start preparing a PR, I thought I'd see if you folks can provide any insight or background.

Suggested Solution

Off the top of my head, I would like to see some kind of search configuration on typedoc.json. Maybe something like this:

{
  ...
  "search": {
    "maxResults": 10,
    "weights": {
     "isClass": 1.1,
     "exactMatch": 2.1,
     "byCategory": {
        "component": 3.4,
        "coreComponent": 4
      }
    }
  }
}

Thoughts?

[Gerrit0]

• exact matches don't seem to get a boost in relevance. We have a class called "Button", but when we search for "button", the main result we're interested in gets muscled down to the 53rd slot by other minor results that have "button" in their name (eg. "Foo.primaryButton"),
• classes don't seem to get a boost over props and other minor features

These two I'd definitely like to do by default. I don't think there's anyone who would not like these changes.

• there's no way to adjust the number of search results

It seems like the optimal number of results to display to me will depend on the screen height/rendered results... I'm certainly open to adjusting this, not sure an option makes sense.

• there's no way to boost on things like categories

Seems like a reasonable request 👍

---

Implementation wise - TypeDoc's current option parser doesn't play nicely with nested objects. Otherwise, I like it

[shmax]

Thanks for the feedback. I'm up to my elbows in the code at the moment, and will try to produce a PR relatively soon.

[Gerrit0]

@shmax now that this has been around for a bit, do you have any thoughts on a good default for searchGroupBoosts? I just noticed that we never ended up creating a default map when updating it to work with 0.23's @group tag

[shmax]

Oh, good question; I figured you would just want to leave it blank and let users season to taste,, but I can look into it a bit when I get a chance. I'll have to do some debugging, anyway, because I tried to use the category boosts the other day in our project, and it didn't seem to do anything. Let me see if I can get back to you this weekend...

[Gerrit0]

It's definitely a good thing that it's configurable, but I think some reasonable default to produce better search results without requiring configuration is a good thing :)

[shmax]

How would you prefer to handle defaults? Two main possibilities off the top of my head:

1. set defaultValue when we invoke options.addDeclaration. Easy enough, but I assume that all the defaults will get written over as soon as the user makes any kind of edit.
2. do something inline in the JavascriptIndexPlugin, eg:

 const kindBoost = kindBoosts[kinds[reflection.kind] ?? ""] ?? defaultGroupBoosts[reflection.kind];

but then you would have a fair amount of bloat in search.js, so maybe we should move the default information into the runtime search stuff?

Let me know what ya think.

[Gerrit0]

The defaultValue is the way to go I think, with the default boosts documented on the website. gzip ought to take care of the extra bloat, so I don't think that's much of an issue

[Gerrit0]

Going to go ahead and close this, PR welcome if you (or anyone) would like to propose some defaults, but just having exact matches boosted does pretty well.