diff --git a/addons/addon-search/README.md b/addons/addon-search/README.md
index 6b9a575b1..88982b2ef 100644
--- a/addons/addon-search/README.md
+++ b/addons/addon-search/README.md
@@ -22,9 +22,11 @@ searchAddon.findNext('foo');
 
 ### Search options
 
-- `decorations`: Highlight all matches and fire `onDidChangeResults` with result counts.
+- `decorations` (`ISearchDecorationOptions`): Enables match highlighting and result tracking; pass a decoration options object (colors may be omitted).
 - `highlightLimit` (constructor option): Caps how many matches are tracked/highlighted (default `1000`).
 - `incremental`: Expands the current selection when the term still matches.
 - `wholeWord`, `regex`, `caseSensitive`: Control match semantics.
 
+`onDidChangeResults` fires after `findNext`/`findPrevious` when `decorations` is set. `clearDecorations()` clears highlights and tracked results but does not emit this event.
+
 See the full [API](https://github.com/xtermjs/xterm.js/blob/master/addons/addon-search/typings/addon-search.d.ts) for more advanced usage.
diff --git a/addons/addon-search/typings/addon-search.d.ts b/addons/addon-search/typings/addon-search.d.ts
index 5541a3df5..c1c56d582 100644
--- a/addons/addon-search/typings/addon-search.d.ts
+++ b/addons/addon-search/typings/addon-search.d.ts
@@ -17,7 +17,8 @@ declare module '@xterm/addon-search' {
 
     /**
      * Whether to search for a whole word, the result is only valid if it's
-     * surrounded in "non-word" characters such as `_`, `(`, `)` or space.
+     * surrounded by start/end of line or non-word separators such as whitespace
+     * and punctuation (for example `(`, `)`, or space).
      */
     wholeWord?: boolean;
 
@@ -42,7 +43,7 @@ declare module '@xterm/addon-search' {
   /**
    * Options for showing decorations when searching.
    */
-  interface ISearchDecorationOptions {
+  export interface ISearchDecorationOptions {
     /**
      * The background color of a match, this must use #RRGGBB format.
      */
@@ -162,7 +163,8 @@ declare module '@xterm/addon-search' {
     readonly onBeforeSearch: IEvent<void>;
 
     /**
-     * When decorations are enabled, fires when the search results change.
+     * When decorations are enabled, fires after `findNext`/`findPrevious` when tracked
+     * search results change. Does not fire from `clearDecorations()`.
      */
     readonly onDidChangeResults: IEvent<ISearchResultChangeEvent>;
   }