chore: convert JSDoc comments to TSDoc (#314)

src/operations/backport-commits.ts

@@ -20,12 +20,12 @@ const cleanRawGitString = (s: string) => {
 /**
  * Runs the git commands to apply backports in a series of cherry-picked commits.
  *
- * @param {BackportOptions} options - an object containing:
+ * @param options - an object containing:
  *   1) dir - the repo directory
  *   2) targetBranch - the target branch
  *   3) patches - a list of patches to apply to the target branch
  *   4) tempBranch - the temporary branch to PR against the target branch
- * @returns {Object} - an object containing the repo initialization directory
+ * @returns false on failure, otherwise an object containing the repo initialization directory
  */
 export const backportCommitsToBranch = async (options: BackportOptions) => {
   log(

src/operations/backport-to-location.ts

@@ -8,9 +8,9 @@ import { SimpleWebHookRepoContext, WebHookPR } from '../types';
 /**
  * Performs a backport to a specified label representing a branch.
  *
- * @param {Probot} robot - an instance of Probot
- * @param {WebHookRepoContext} context - the context of the event that was triggered
- * @param {PullsGetResponseLabelsItem} label - the label representing the target branch for backporting
+ * @param robot - an instance of Probot
+ * @param context - the context of the event that was triggered
+ * @param label - the label representing the target branch for backporting
  */
 export const backportToLabel = async (
   robot: Probot,
@@ -59,9 +59,9 @@ export const backportToLabel = async (
 /**
  * Performs a backport to a specified target branch.
  *
- * @param {Probot} robot - an instance of Probot
- * @param {WebHookRepoContext} context - the context of the event that was triggered
- * @param {string} targetBranch - the branch to which the backport will be performed
+ * @param robot - an instance of Probot
+ * @param context - the context of the event that was triggered
+ * @param targetBranch - the branch to which the backport will be performed
  */
 export const backportToBranch = async (
   robot: Probot,

src/operations/init-repo.ts

@@ -45,8 +45,8 @@ async function updateRepoCache({ slug, accessToken }: InitRepoOptions) {
 /**
  * Initializes the cloned repo trop will use to run backports.
  *
- * @param {InitRepoOptions} options - repo and payload for repo initialization
- * @returns {{dir: string}} - an object containing the repo initialization directory
+ * @param options - repo and payload for repo initialization
+ * @returns an object containing the repo initialization directory
  */
 export const initRepo = async ({
   slug,

src/operations/setup-remotes.ts

@@ -6,10 +6,10 @@ import { LogLevel } from '../enums';
 /**
  * Sets up remotes that trop will run backports with.
  *
- * @param {RemotesOptions} options - an object containing:
+ * @param options - an object containing:
  *  1) dir - the repo directory
  *  2) remotes - the list of remotes to set on the initialized git repository
- * @returns {Object} - an object containing the repo initialization directory
+ * @returns an object containing the repo initialization directory
  */
 export const setupRemotes = async (options: RemotesOptions) => {
   log('setupRemotes', LogLevel.INFO, 'Setting up git remotes');

src/operations/update-manual-backport.ts

@@ -13,9 +13,9 @@ import { log } from '../utils/log-util';
  * Updates the labels on a backport's original PR as well as comments with links
  * to the backport if it's a newly opened PR.
  *
- * @param {Context} context - the context of the event that was triggered
- * @param {PRChange} type - the type of PR status change: either OPEN or CLOSE
- * @param {number} oldPRNumber - the number corresponding to the backport's original PR
+ * @param context - the context of the event that was triggered
+ * @param type - the type of PR status change: either OPEN or CLOSE
+ * @param oldPRNumber - the number corresponding to the backport's original PR
  */
 export const updateManualBackport = async (
   context: WebHookPRContext,

src/utils/branch-util.ts

@@ -66,8 +66,8 @@ function comparePart(a: string, b: string): number {
 /**
  * Fetches an array of the currently supported branches for a repository.
  *
- * @param {Context} context - the context of the event that was triggered
- * @returns {Promise<string[]>} - an array of currently supported branches in x-y-z format
+ * @param context - the context of the event that was triggered
+ * @returns an array of currently supported branches in x-y-z format
  */
 export async function getSupportedBranches(
   context: Pick<WebHookRepoContext, 'octokit' | 'repo'>,

src/utils/env-util.ts

@@ -5,9 +5,9 @@ import { LogLevel } from '../enums';
  * Checks that a given environment variable exists, and returns
  * its value if it does. Conditionally throws an error on failure.
  *
- * @param {string} envVar - the environment variable to retrieve
- * @param {string} defaultValue - default value to use if no environment var is found
- * @returns {string} - the value of the env var being checked, or the default value if one is passed
+ * @param envVar - the environment variable to retrieve
+ * @param defaultValue - default value to use if no environment var is found
+ * @returns the value of the env var being checked, or the default value if one is passed
  */
 export function getEnvVar(envVar: string, defaultValue?: string): string {
   log('getEnvVar', LogLevel.INFO, `Fetching env var '${envVar}'`);

src/utils/log-util.ts

@@ -3,9 +3,9 @@ import { LogLevel } from '../enums';
 /**
  * Logs information about different actions taking place to console.
  *
- * @param {string} functionName - the name of the function where the logging is happening
- * @param {LogLevel }logLevel - the severity level of the log
- * @param {any[]} message - the message to write to console
+ * @param functionName - the name of the function where the logging is happening
+ * @param logLevel - the severity level of the log
+ * @param message - the message to write to console
  */
 export const log = (
   functionName: string,

src/utils/token-util.ts

@@ -6,9 +6,9 @@ import { SimpleWebHookRepoContext } from '../types';
 /**
  * Creates and returns an installation token for a GitHub App.
  *
- * @param {Application} robot - an instance of Probot
- * @param {Context} context - the context of the event that was triggered
- * @returns {Promise<string>} - a string representing a GitHub App installation token
+ * @param robot - an instance of Probot
+ * @param context - the context of the event that was triggered
+ * @returns a string representing a GitHub App installation token
  */
 export const getRepoToken = async (
   robot: Probot,