Add doc for Result

Author: henrymercer

lib/init-action.js

@@ -373,7 +373,7 @@ async function run(startedAt: Date) {
       logger,
     });
 
-    if (repositoryProperties.isError()) {
+    if (repositoryProperties.isFailure()) {
       addDiagnostic(
         config,
         // Arbitrarily choose the first language. We could also choose all languages, but that
@@ -810,25 +810,25 @@ async function loadRepositoryProperties(
       "Skipping loading repository properties because the repository is owned by a user and " +
         "therefore cannot have repository properties.",
     );
-    return Result.ok({});
+    return Result.success({});
   }
 
   if (!(await features.getValue(Feature.UseRepositoryProperties))) {
     logger.debug(
       "Skipping loading repository properties because the UseRepositoryProperties feature flag is disabled.",
     );
-    return Result.ok({});
+    return Result.success({});
   }
 
   try {
-    return Result.ok(
+    return Result.success(
       await loadPropertiesFromApi(gitHubVersion, logger, repositoryNwo),
     );
   } catch (error) {
     logger.warning(
       `Failed to load repository properties: ${getErrorMessage(error)}`,
     );
-    return Result.error(error);
+    return Result.failure(error);
   }
 }
 

src/init-action.ts

@@ -1293,32 +1293,42 @@ export function joinAtMost(
   return array.join(separator);
 }
 
+/** A success result. */
 type Success<T> = Result<T, never>;
+/** A failure result. */
 type Failure<E> = Result<never, E>;
 
+/**
+ * A simple result type representing either a success or a failure.
+ */
 export class Result<T, E> {
   private constructor(
     private readonly _ok: boolean,
     public readonly value: T | E,
   ) {}
 
-  static ok<T>(value: T): Success<T> {
+  /** A success result. */
+  static success<T>(value: T): Success<T> {
     return new Result(true, value) as Success<T>;
   }
 
-  static error<E>(error: E): Failure<E> {
-    return new Result(false, error) as Failure<E>;
+  /** A failure result. */
+  static failure<E>(value: E): Failure<E> {
+    return new Result(false, value) as Failure<E>;
   }
 
-  isOk(): this is Success<T> {
+  /** Whether this result represents a success. */
+  isSuccess(): this is Success<T> {
     return this._ok;
   }
 
-  isError(): this is Failure<E> {
+  /** Whether this result represents a failure. */
+  isFailure(): this is Failure<E> {
     return !this._ok;
   }
 
+  /** Get the value if this is a success, or return the default value if this is a failure. */
   orElse(defaultValue: T): T {
-    return this.isOk() ? this.value : defaultValue;
+    return this.isSuccess() ? this.value : defaultValue;
   }
 }