Merge pull request #29 from pihart/jsdoc-throws

Use JSDoc syntax for @throws annotations (when applicable)
pihart · Mar 23, 2021 · c121716 · c121716
2 parents 9b5928b + 481ce05
commit c121716
Show file tree

Hide file tree

Showing 3 changed files with 10 additions and 11 deletions.
diff --git a/src/lib/assert.ts b/src/lib/assert.ts
@@ -3,8 +3,9 @@ import { CustomError } from "./error";
 export class AssertionError extends CustomError {}
 
 /**
- * Asserts `bool`
- * @throws `errorConstructor`
+ * Asserts {@param bool}
+ * @param errorConstructor A constructor for the thrown error class
+ * @throws {@param errorConstructor}
  */
 export function Assert(
   bool: boolean,

diff --git a/src/lib/email.ts b/src/lib/email.ts
@@ -31,7 +31,7 @@ export namespace Email {
 
   /**
    * Assert using RFC 5322 email validation
-   * @throws {@linkcode InvalidEmailException}
+   * @throws {InvalidEmailException} If {@param str} is not a syntactically valid email
    * @warn Not restrictive; see {@linkcode roughValidate}
    */
   export const roughAssert = (str: string): asserts str is Email => {

diff --git a/src/lib/network.ts b/src/lib/network.ts
@@ -51,9 +51,8 @@ export class Network {
    *
    * @param filePath The network URL of file to be fetched
    * @return The resource as parsed JSON object
-   * @throws
-   * [[`ResourceNotFoundException`]] if the request fails,
-   * defined by the status being in [200, 300)
+   * @throws {ResourceNotFoundException} if the request fails,
+   * defined by the status not being in [200, 300)
    * @warn Doesn't implement timeout logic
    * @deprecated
    */
@@ -78,9 +77,8 @@ export class Network {
    * @return
    * The XHR as a Promise,
    * with a [[`ResourceNotFoundException`]] in case of rejection
-   * @throws
-   * [[`ResourceNotFoundException`]] if the request fails,
-   * as defined by {@param resolveCondition}
+   * @throws {ResourceNotFoundException} if the request fails,
+   * as defined by the negation of {@param resolveCondition}
    * @warn Doesn't implement timeout logic
    * @deprecated
    */
@@ -115,7 +113,7 @@ export class Network {
    * Use instead of `window.fetch` because it rejects failed transactions.
    *
    * @return The result of the request to the resource, parsed as JSON, if it is `ok`
-   * @throws [[`ResourceNotFoundException`]] if not `ok`
+   * @throws {ResourceNotFoundException} if not `ok`
    */
   static async loadJSON(input: RequestInfo, init?: RequestInit): Promise<any> {
     const response = await Network.fetch(input, init);
@@ -128,7 +126,7 @@ export class Network {
    * Use instead of `window.fetch` because it rejects failed transactions.
    *
    * @return The result of `window.fetch`, if it is `ok`
-   * @throws [[`ResourceNotFoundException`]] if not `ok`
+   * @throws {ResourceNotFoundException} if not `ok`
    */
   static async fetch(
     input: RequestInfo,