Clean up docs for text search APIs

src/vscode-dts/vscode.proposed.findTextInFilesNew.d.ts

@@ -155,7 +155,7 @@ declare module 'vscode' {
  * Search text in files across all {@link workspace.workspaceFolders workspace folders} in the workspace.
  * @param query The query parameters for the search - the search string, whether it's case-sensitive, or a regex, or matches whole words.
  * @param options An optional set of query options.
- * @param callback A callback, called for each result
+ * @param callback A callback, called for each {@link TextSearchResultNew result}. This can be a direct match, or context that surrounds a match.
  * @param token A token that can be used to signal cancellation to the underlying search engine.
  * @return A thenable that resolves when the search is complete.
  */

src/vscode-dts/vscode.proposed.textSearchProviderNew.d.ts

@@ -8,31 +8,47 @@ declare module 'vscode' {
  // https://github.com/microsoft/vscode/issues/59921
 
  /**
- * The parameters of a query for text search.
+ * The parameters of a query for text search. All optional booleans default to `false`.
  */
  export interface TextSearchQueryNew {
  /**
  * The text pattern to search for.
+ *
+ * If explicitly contains a newline character (`\n`), the default search behavior
+ * will automatically enable {@link isMultiline}.
  */
  pattern: string;
 
  /**
  * Whether or not `pattern` should match multiple lines of text.
+ *
+ * If using the default search provider, this will be interpreted as `true` if
+ * `pattern` contains a newline character (`\n`).
  */
  isMultiline?: boolean;
 
  /**
  * Whether or not `pattern` should be interpreted as a regular expression.
+ *
+ * If using the default search provider, this will be interpreted case-insensitively
+ * if {@link isCaseSensitive} is `false` or not set.
  */
  isRegExp?: boolean;
 
  /**
  * Whether or not the search should be case-sensitive.
+ *
+ * If using the default search provider, this can be affected by the `search.smartCase` setting.
+ * See the setting description for more information.
  */
  isCaseSensitive?: boolean;
 
  /**
  * Whether or not to search for whole word matches only.
+ *
+ * If enabled, the default search provider will check for boundary characters
+ * (regex pattern `\b`) surrounding the {@link pattern} to see whether something
+ * is a word match.
  */
  isWordMatch?: boolean;
  }
@@ -138,7 +154,17 @@ declare module 'vscode' {
  }
 
  /**
- * The main match information for a {@link TextSearchResultNew}.
+ * A query match instance in a file.
+ *
+ * For example, consider this excerpt:
+ *
+ * ```ts
+ * const bar = 1;
+ * console.log(bar);
+ * const foo = bar;
+ * ```
+ *
+ * If the query is `log`, then the line `console.log(bar);` should be represented using a {@link TextSearchMatchNew}.
  */
  export class TextSearchMatchNew {
  /**
@@ -171,7 +197,20 @@ declare module 'vscode' {
  }
 
  /**
- * The potential context information for a {@link TextSearchResultNew}.
+ * The context lines of text that are not a part of a match,
+ * but that surround a match line of type {@link TextSearchMatchNew}.
+ *
+ * For example, consider this excerpt:
+ *
+ * ```ts
+ * const bar = 1;
+ * console.log(bar);
+ * const foo = bar;
+ * ```
+ *
+ * If the query is `log`, then the lines `const bar = 1;` and `const foo = bar;`
+ * should be represented using two separate {@link TextSearchContextNew} for the search instance.
+ * This example assumes that the finder requests one line of surrounding context.
  */
  export class TextSearchContextNew {
  /**
@@ -199,7 +238,8 @@ declare module 'vscode' {
  }
 
  /**
- * A result payload for a text search, pertaining to matches within a single file.
+ * A result payload for a text search, pertaining to {@link TextSearchMatchNew matches}
+ * and its associated {@link TextSearchContextNew context} within a single file.
  */
  export type TextSearchResultNew = TextSearchMatchNew | TextSearchContextNew;
 
@@ -213,7 +253,8 @@ declare module 'vscode' {
  * Provide results that match the given text pattern.
  * @param query The parameters for this query.
  * @param options A set of options to consider while searching.
- * @param progress A progress callback that must be invoked for all results.
+ * @param progress A progress callback that must be invoked for all {@link TextSearchResultNew results}.
+ * These results can be direct matches, or context that surrounds matches.
  * @param token A cancellation token.
  */
  provideTextSearchResults(query: TextSearchQueryNew, options: TextSearchProviderOptions, progress: Progress<TextSearchResultNew>, token: CancellationToken): ProviderResult<TextSearchCompleteNew>;