From 69bb49e530fbf1a0afc3335211bacb9fad68f6d9 Mon Sep 17 00:00:00 2001
From: Paul Gschwendtner <paulgschwendtner@gmail.com>
Date: Wed, 9 Sep 2020 14:44:14 +0200
Subject: [PATCH] refactor(dev-infra): cleanup comments in git utilities
 (#38656)

Cleans up outdated comments in the shared dev-infra Git
utilities. We also export the Graphql client for consistency
as we expose the `GithubClient` and `GitClient` too.

PR Close #38656
---
 dev-infra/utils/git/github.ts | 15 +++++----------
 dev-infra/utils/git/index.ts  | 12 +++++++-----
 2 files changed, 12 insertions(+), 15 deletions(-)

diff --git a/dev-infra/utils/git/github.ts b/dev-infra/utils/git/github.ts
index b2aaa8b3f0..1d368bb9f0 100644
--- a/dev-infra/utils/git/github.ts
+++ b/dev-infra/utils/git/github.ts
@@ -69,18 +69,13 @@ export class GithubClient extends Octokit {
 }
 
 /**
- * An object representation of a GraphQL Query to be used as a response type and to generate
- * a GraphQL query string.
+ * An object representation of a GraphQL Query to be used as a response type and
+ * to generate a GraphQL query string.
  */
-type GraphQLQueryObject = Parameters<typeof query>[1];
+export type GraphQLQueryObject = Parameters<typeof query>[1];
 
-/**
- * A client for interacting with Github's GraphQL API.
- *
- * This class is intentionally not exported as it should always be access/used via a
- * _GithubClient instance.
- */
-class GithubGraphqlClient {
+/** A client for interacting with Github's GraphQL API. */
+export class GithubGraphqlClient {
   /** The Github GraphQL (v4) API. */
   private graqhql = graphql;
 
diff --git a/dev-infra/utils/git/index.ts b/dev-infra/utils/git/index.ts
index 1322d62652..0478826671 100644
--- a/dev-infra/utils/git/index.ts
+++ b/dev-infra/utils/git/index.ts
@@ -33,16 +33,16 @@ export class GitCommandError extends Error {
 }
 
 /**
- * Common client for performing Git interactions.
+ * Common client for performing Git interactions with a given remote.
  *
  * Takes in two optional arguments:
- *   _githubToken: the token used for authentifation in github interactions, by default empty
+ *   `githubToken`: the token used for authentication in Github interactions, by default empty
  *     allowing readonly actions.
- *   _config: The dev-infra configuration containing GitClientConfig information, by default
- *     loads the config from the default location.
+ *   `config`: The dev-infra configuration containing information about the remote. By default
+ *     the dev-infra configuration is loaded with its Github configuration.
  **/
 export class GitClient {
-  /** Short-hand for accessing the remote configuration. */
+  /** Short-hand for accessing the default remote configuration. */
   remoteConfig = this._config.github;
   /** Octokit request parameters object for targeting the configured remote. */
   remoteParams = {owner: this.remoteConfig.owner, repo: this.remoteConfig.name};
@@ -91,6 +91,8 @@ export class GitClient {
     // commands unless the `stdio` is explicitly to `ignore` (which is equivalent to silent).
     // Note that we do not want to print the token if is contained in the command. It's common
     // to share errors with others if the tool failed, and we do not want to leak tokens.
+    // TODO: Add support for configuring this on a per-client basis. Some tools do not want
+    // to print the Git command messages to the console at all (e.g. to maintain clean output).
     const printFn = options.stdio !== 'ignore' ? info : debug;
     printFn('Executing: git', this.omitGithubTokenFromMessage(args.join(' ')));