Add documentation

Author: robertbrignull

extensions/ql-vscode/src/common/authentication.ts

@@ -1,14 +1,34 @@
 import * as Octokit from "@octokit/rest";
 
+/**
+ * An interface providing methods for obtaining access tokens
+ * or an octokit instance for making HTTP requests.
+ */
 export interface Credentials {
   /**
-   * Creates or returns an instance of Octokit.
+   * Returns an authenticated instance of Octokit.
+   * May prompt the user to log in and grant permission to use their
+   * token, if they have not already done so.
    *
    * @returns An instance of Octokit.
    */
   getOctokit(): Promise<Octokit.Octokit>;
 
+  /**
+   * Returns an OAuth access token.
+   * May prompt the user to log in and grant permission to use their
+   * token, if they have not already done so.
+   *
+   * @returns An OAuth access token.
+   */
   getAccessToken(): Promise<string>;
 
+  /**
+   * Returns an OAuth access token if one is available.
+   * If a token is not available this will return undefined and
+   * will not prompt the user to log in.
+   *
+   * @returns An OAuth access token, or undefined.
+   */
   getExistingAccessToken(): Promise<string | undefined>;
 }

extensions/ql-vscode/test/factories/authentication.ts

@@ -18,6 +18,10 @@ function makeTestOctokit(octokit: Octokit.Octokit): Credentials {
   };
 }
 
+/**
+ * Get a Credentials instance that calls a stub function instead
+ * of making real HTTP requests.
+ */
 export function testCredentialsWithStub(
   requestSpy?: jest.SpyInstance<RequestInterface<object>>,
 ): Credentials {
@@ -29,6 +33,10 @@ export function testCredentialsWithStub(
   return makeTestOctokit({ request } as any);
 }
 
+/**
+ * Get a Credentials instance that returns a real octokit instance,
+ * optionally authenticated with a given token.
+ */
 export function testCredentialsWithRealOctokit(token?: string): Credentials {
   return makeTestOctokit(new Octokit.Octokit({ auth: token, retry }));
 }