Merge pull request #224654 from microsoft/colorful-mastodon

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>;