Skip to content

Commit 3a4f195

Browse files
committed
Improve JSDocs in diff-informed/index.ts
1 parent 2465f77 commit 3a4f195

2 files changed

Lines changed: 59 additions & 10 deletions

File tree

‎src/actions-util.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,8 +78,12 @@ export function getTemporaryDirectory(env: ReadOnlyEnv = getEnv()): string {
7878
);
7979
}
8080

81+
/** The filename used to persist PR diff ranges. */
8182
const PR_DIFF_RANGE_JSON_FILENAME = "pr-diff-range.json";
8283

84+
/**
85+
* Gets the full path of the file used to persist PR diff ranges.
86+
*/
8387
export function getDiffRangesJsonFilePath(env: Env = getEnv()): string {
8488
return path.join(getTemporaryDirectory(env), PR_DIFF_RANGE_JSON_FILENAME);
8589
}

‎src/diff-informed/index.ts‎

Lines changed: 55 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -13,11 +13,15 @@ import { getErrorMessage, GitHubVariant, satisfiesGHESVersion } from "../util";
1313
* This interface is an abbreviated version of the file diff object returned by
1414
* the GitHub API.
1515
*/
16-
interface FileDiff {
16+
export interface FileDiff {
17+
/** The name of the file that has changed. */
1718
filename: string;
19+
/** The number of changes. */
1820
changes: number;
19-
// A patch may be absent if the file is binary, if the file diff is too large,
20-
// or if the file is unchanged.
21+
/**
22+
* The diff, if available. It may be absent if the file is binary, if the file diff is too large,
23+
* or if the file is unchanged.
24+
*/
2125
patch?: string | undefined;
2226
}
2327

@@ -93,13 +97,23 @@ export async function prepareDiffInformedAnalysis(
9397
}
9498
}
9599

100+
/** Describes a changed line range in a file. */
96101
export interface DiffThunkRange {
97102
/** Relative path from the repository root, using forward slashes as separators. */
98103
path: string;
104+
/** The starting line of the change (1-based and inclusive). */
99105
startLine: number;
106+
/** The last line of the change (1-based and inclusive). */
100107
endLine: number;
101108
}
102109

110+
/**
111+
* Writes an array of {@link DiffThunkRange} objects to the file given by
112+
* {@link actionsUtil.getDiffRangesJsonFilePath}.
113+
*
114+
* @param logger The logger to use.
115+
* @param ranges The changed line ranges to write.
116+
*/
103117
export function writeDiffRangesJsonFile(
104118
logger: Logger,
105119
ranges: DiffThunkRange[],
@@ -112,6 +126,13 @@ export function writeDiffRangesJsonFile(
112126
);
113127
}
114128

129+
/**
130+
* Reads an array of {@link DiffThunkRange} objects from the file given by
131+
* {@link actionsUtil.getDiffRangesJsonFilePath}.
132+
*
133+
* @param logger The logger to use.
134+
* @returns The array of {@link DiffThunkRange} objects or `undefined` if the file couldn't be read.
135+
*/
115136
export function readDiffRangesJsonFile(
116137
logger: Logger,
117138
): DiffThunkRange[] | undefined {
@@ -138,12 +159,12 @@ export function readDiffRangesJsonFile(
138159
* Return the file line ranges that were added or modified in the pull request.
139160
*
140161
* @param branches The base and head branches of the pull request.
141-
* @param logger
142-
* @returns An array of tuples, where each tuple contains the relative path of a
143-
* file (relative to the repository root, as returned by the GitHub compare API),
144-
* the start line and the end line (both 1-based and inclusive) of an
145-
* added or modified range in that file. Returns `undefined` if the action was
146-
* not triggered by a pull request or if there was an error.
162+
* @param logger The logger to use.
163+
*
164+
* @returns
165+
* An array of {@link DiffThunkRange} objects, where each describes a line range in a file
166+
* that was changed in the pull request described by {@link branches} or `undefined` if
167+
* we were unable to compute them.
147168
*/
148169
export async function getPullRequestEditedDiffRanges(
149170
branches: PullRequestBranches,
@@ -182,7 +203,8 @@ export async function getPullRequestEditedDiffRanges(
182203
*
183204
* @param branches The base and head branches of the pull request, as returned
184205
* by `getDiffInformedAnalysisBranches`.
185-
* @param logger
206+
* @param logger The logger to use.
207+
*
186208
* @returns `true` if the diff ranges were successfully computed and persisted,
187209
* otherwise `false`.
188210
*/
@@ -203,6 +225,19 @@ export async function computeAndPersistDiffRanges(
203225
return true;
204226
}
205227

228+
/**
229+
* Fetch an array of {@link FileDiff} objects using the GitHub API describing the changed files
230+
* in the pull request with the base and head refs given by {@link branches}.
231+
*
232+
* @param branches The pull request branch refs.
233+
* @param logger The logger to use.
234+
*
235+
* @throws Non-HTTP errors that occur while fetching the file diffs.
236+
*
237+
* @returns
238+
* An array of {@link FileDiff} objects describing the changed files in the PR, or
239+
* `undefined` if we couldn't obtain the changed files from the API.
240+
*/
206241
async function getFileDiffsWithBasehead(
207242
branches: PullRequestBranches,
208243
logger: Logger,
@@ -243,6 +278,16 @@ async function getFileDiffsWithBasehead(
243278
}
244279
}
245280

281+
/**
282+
* Extracts an array of {@link DiffThunkRange} objects from {@link fileDiff}.
283+
*
284+
* @param fileDiff The {@link FileDiff} object describing changes to a particular file.
285+
* @param logger The logger to use.
286+
*
287+
* @returns
288+
* The {@link DiffThunkRange} objects extracted from {@link fileDiff},
289+
* or `undefined` if there are none that could be extracted.
290+
*/
246291
function getDiffRanges(
247292
fileDiff: FileDiff,
248293
logger: Logger,

0 commit comments

Comments
 (0)