Adds comments and clarifies forceSingleLine param

src/env/node/git/localGitProvider.ts

@@ -24,7 +24,7 @@ import type {
 } from '../../../@types/vscode.git';
 import { configuration } from '../../../configuration';
 import { BuiltInGitConfiguration, DocumentSchemes, GlyphChars } from '../../../constants';
-import { Container } from '../../../container';
+import type { Container } from '../../../container';
 import { StashApplyError, StashApplyErrorReason } from '../../../git/errors';
 import {
 	GitProvider,
@@ -729,7 +729,7 @@ export class LocalGitProvider implements GitProvider, Disposable {
 		return promise;
 	}
 
-	async getBlameForFileContentsCore(
+	private async getBlameForFileContentsCore(
 		uri: GitUri,
 		contents: string,
 		document: TrackedDocument<GitDocumentState>,
@@ -774,10 +774,10 @@ export class LocalGitProvider implements GitProvider, Disposable {
 	@log()
 	async getBlameForLine(
 		uri: GitUri,
-		editorLine: number, // editor lines are 0-based
-		options: { skipCache?: boolean } = {},
+		editorLine: number,
+		options?: { forceSingleLine?: boolean },
 	): Promise<GitBlameLine | undefined> {
-		if (!options.skipCache && this.useCaching) {
+		if (!options?.forceSingleLine && this.useCaching) {
 			const blame = await this.getBlameForFile(uri);
 			if (blame == null) return undefined;
 
@@ -824,11 +824,11 @@ export class LocalGitProvider implements GitProvider, Disposable {
 	@log<LocalGitProvider['getBlameForLineContents']>({ args: { 2: '<contents>' } })
 	async getBlameForLineContents(
 		uri: GitUri,
-		editorLine: number, // editor lines are 0-based
+		editorLine: number,
 		contents: string,
-		options: { skipCache?: boolean } = {},
+		options?: { forceSingleLine?: boolean },
 	): Promise<GitBlameLine | undefined> {
-		if (!options.skipCache && this.useCaching) {
+		if (!options?.forceSingleLine && this.useCaching) {
 			const blame = await this.getBlameForFileContents(uri, contents);
 			if (blame == null) return undefined;
 

src/git/gitProvider.ts

@@ -104,18 +104,38 @@ export interface GitProvider {
 			remote?: string | undefined;
 		},
 	): Promise<void>;
+	/**
+	 * Returns the blame of a file
+	 * @param uri The uri of the file to blame
+	 */
 	getBlameForFile(uri: GitUri): Promise<GitBlame | undefined>;
+	/**
+	 * Returns the blame of a file, using the editor contents (for dirty editors)
+	 * @param uri The uri of the file to blame
+	 * @param contents The editor contents to use
+	 */
 	getBlameForFileContents(uri: GitUri, contents: string): Promise<GitBlame | undefined>;
+	/**
+	 * Returns the blame of a single line
+	 * @param uri The uri of the file to blame
+	 * @param line The editor line number (0-based) to blame (Git is 1-based)
+	 */
 	getBlameForLine(
 		uri: GitUri,
 		editorLine: number,
-		options?: { skipCache?: boolean | undefined },
+		options?: { forceSingleLine?: boolean },
 	): Promise<GitBlameLine | undefined>;
+	/**
+	 * Returns the blame of a single line, using the editor contents (for dirty editors)
+	 * @param uri The uri of the file to blame
+	 * @param line The editor line number (0-based) to blame (Git is 1-based)
+	 * @param contents The editor contents to use
+	 */
 	getBlameForLineContents(
 		uri: GitUri,
 		editorLine: number,
 		contents: string,
-		options?: { skipCache?: boolean | undefined },
+		options?: { forceSingleLine?: boolean },
 	): Promise<GitBlameLine | undefined>;
 	getBlameForRange(uri: GitUri, range: Range): Promise<GitBlameLines | undefined>;
 	getBlameForRangeContents(uri: GitUri, range: Range, contents: string): Promise<GitBlameLines | undefined>;

src/git/gitProviderService.ts

@@ -25,7 +25,7 @@ import {
 	setContext,
 	WorkspaceState,
 } from '../constants';
-import { Container } from '../container';
+import type { Container } from '../container';
 import { ProviderNotFoundError } from '../errors';
 import { Logger } from '../logger';
 import { Arrays, debug, gate, Iterables, log, Paths, Promises, Strings } from '../system';
@@ -764,33 +764,53 @@ export class GitProviderService implements Disposable {
 	}
 
 	@log()
+	/**
+	 * Returns the blame of a file
+	 * @param uri The uri of the file to blame
+	 */
 	async getBlameForFile(uri: GitUri): Promise<GitBlame | undefined> {
 		const { provider } = this.getProvider(uri);
 		return provider.getBlameForFile(uri);
 	}
 
 	@log<GitProviderService['getBlameForFileContents']>({ args: { 1: '<contents>' } })
+	/**
+	 * Returns the blame of a file, using the editor contents (for dirty editors)
+	 * @param uri The uri of the file to blame
+	 * @param contents The editor contents to use
+	 */
 	async getBlameForFileContents(uri: GitUri, contents: string): Promise<GitBlame | undefined> {
 		const { provider } = this.getProvider(uri);
 		return provider.getBlameForFileContents(uri, contents);
 	}
 
 	@log()
+	/**
+	 * Returns the blame of a single line
+	 * @param uri The uri of the file to blame
+	 * @param line The editor line number (0-based) to blame (Git is 1-based)
+	 */
 	async getBlameForLine(
 		uri: GitUri,
-		editorLine: number, // editor lines are 0-based
-		options?: { skipCache?: boolean },
+		editorLine: number,
+		options?: { forceSingleLine?: boolean },
 	): Promise<GitBlameLine | undefined> {
 		const { provider } = this.getProvider(uri);
 		return provider.getBlameForLine(uri, editorLine, options);
 	}
 
 	@log<GitProviderService['getBlameForLineContents']>({ args: { 2: '<contents>' } })
+	/**
+	 * Returns the blame of a single line, using the editor contents (for dirty editors)
+	 * @param uri The uri of the file to blame
+	 * @param line The editor line number (0-based) to blame (Git is 1-based)
+	 * @param contents The editor contents to use
+	 */
 	async getBlameForLineContents(
 		uri: GitUri,
-		editorLine: number, // editor lines are 0-based
+		editorLine: number,
 		contents: string,
-		options?: { skipCache?: boolean },
+		options?: { forceSingleLine?: boolean },
 	): Promise<GitBlameLine | undefined> {
 		const { provider } = this.getProvider(uri);
 		return provider.getBlameForLineContents(uri, editorLine, contents, options);