dotnet / dotnet/docfx

[Feature Request] Add option to debounce keystrokes in API search

Open
#10,043 9 comments 0 reactions 0 assignees View on GitHub
template
Dominant language
C#
Stars
4.4k
Forks
890
Avg merge
2h 9m
Merged PRs (30d)
11

Description

**Is your feature request related to a problem? Please describe.**

I use DocFX to generate the docs for a very large solution with a huge API. I like the API search feature in the **template** but when typing a search string, due to the size of the searched code, this introduces high web browser CPU usage and freezes my browser UI for a few seconds. I appreciate that it's probably not possible _to simply make the search quicker_ but I noticed that the search seems to begin the very moment I type the first character of my search string. That seems to be wasting compute resources performing a search which is going to be discarded. It also means I can't see the rest of characters I'm typing into the search text box until the search has completed. Sometimes that means I have to use backspace and correct typos, triggering more wasteful search operations.

**Describe the solution you'd like**

I'd [like a template option, likely alongside `_enableSearch`](https://dotnet.github.io/docfx/docs/template.html?tabs=modern) which is of type nullable integer. If `null` then the behaviour is as the template currently functions; the client side logic begins searching as soon as a character is received in the textbox. If not null and a positive integer is specified then this is the number of milliseconds that [the input is debounced](https://www.techtarget.com/whatis/definition/debouncing) before a search begins. Obviously a negative integer here is nonsense; it should either be treated the same as null or should raise an error, as appropriate to DocFx's conventions.

A default value of `null` seems sensible, to maintain the current behaviour, for small-to-medium sized solutions. In my solution, I would try an initial debounce-timer of around 350ms. That seems long enough that someone who is typing - and knows what they are typing - can likely type it all without triggering wasteful searches. It should be short enough though, that they aren't frustrated waiting for it.

**Describe alternatives you've considered**

In truly large projects I imagine that the entire search functionality should be moved server-side with a completely custom impl that is outside the scope of DocFX. We don't have the capacity/motivation to do that.

I suppose I could work around the problem by copy-pasting my search term into the search text box, but that is not as convenient.

**Additional context**

For reference, this is the API search tool I'm referring to.

![image](https://github.com/dotnet/docfx/assets/982047/816240b1-72f5-4434-a2fa-53c0415b08cf)

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.