From 107f15df033c955ea7698690d2bbeb1ee34fa325 Mon Sep 17 00:00:00 2001
From: Paul Gschwendtner <paulgschwendtner@gmail.com>
Date: Wed, 2 Jun 2021 18:47:01 +0200
Subject: [PATCH] refactor(dev-infra): add JSDoc throws description to
 assertion functions (#42454)

Adds the JSDoc `@throws` annotation to functions that would throw
within in the ng-dev tool. We want to add `@throws` so clearly
communicate if the invocation of a function results in errors or not.

This helps if IDEs show the `@throws` annotation on invocation, or
if TS ever lands a feature like Java `throws`, with more fine-grained
and typed error handling.

PR Close #42454
---
 dev-infra/pr/merge/pull-request.ts | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)

diff --git a/dev-infra/pr/merge/pull-request.ts b/dev-infra/pr/merge/pull-request.ts
index 1b2e8fa12d..87ff847c0e 100644
--- a/dev-infra/pr/merge/pull-request.ts
+++ b/dev-infra/pr/merge/pull-request.ts
@@ -170,8 +170,7 @@ type RawPullRequest = typeof PR_SCHEMA;
 async function fetchPullRequestFromGithub(
     git: GitClient<true>, prNumber: number): Promise<RawPullRequest|null> {
   try {
-    const x = await getPr(PR_SCHEMA, prNumber, git);
-    return x;
+    return await getPr(PR_SCHEMA, prNumber, git);
   } catch (e) {
     // If the pull request could not be found, we want to return `null` so
     // that the error can be handled gracefully.
@@ -188,8 +187,9 @@ export function isPullRequest(v: PullRequestFailure|PullRequest): v is PullReque
 }
 
 /**
- * Assert the commits provided are allowed to merge to the provided target label, throwing a
- * PullRequestFailure otherwise.
+ * Assert the commits provided are allowed to merge to the provided target label,
+ * throwing an error otherwise.
+ * @throws {PullRequestFailure}
  */
 function assertChangesAllowForTargetLabel(
     commits: Commit[], label: TargetLabel, config: MergeConfig) {
@@ -230,6 +230,7 @@ function assertChangesAllowForTargetLabel(
 /**
  * Assert the pull request has the proper label for breaking changes if there are breaking change
  * commits, and only has the label if there are breaking change commits.
+ * @throws {PullRequestFailure}
  */
 function assertCorrectBreakingChangeLabeling(
     commits: Commit[], labels: string[], config: MergeConfig) {
@@ -248,7 +249,10 @@ function assertCorrectBreakingChangeLabeling(
 }
 
 
-/** Assert the pull request is pending, not closed, merged or in draft. */
+/**
+ * Assert the pull request is pending, not closed, merged or in draft.
+ * @throws {PullRequestFailure} if the pull request is not pending.
+ */
 function assertPendingState(pr: RawPullRequest) {
   if (pr.isDraft) {
     throw PullRequestFailure.isDraft();