extension/src: rename telemetry state starting to running

- The _state of telemetry reporter is reflecting whether an
ongoing telemetry data write is happening. flush method
set the _state to STARTING before calling vscgo to write
telemetry data. Also the RUNNING state is not being referenced
(safe to remove). However, RUNNING is more accurate compares to
STARTING so I replace all STARTING appearance with RUNNING.
- Replace comments with JSDoc, explain public methods of
telemetry reporter class in more detail.

For #3697

Change-Id: Iff696748b7550d5fb40853be99bb6054665b518a
Reviewed-on: https://go-review.googlesource.com/c/vscode-go/+/660095
kokoro-CI: kokoro <[email protected]>
Reviewed-by: Peter Weinberger <[email protected]>
LUCI-TryBot-Result: Go LUCI <[email protected]>

Author: h9jiang

extension/src/goTelemetry.ts

@@ -13,17 +13,25 @@ import * as cp from 'child_process';
 import { getWorkspaceFolderPath } from './util';
 import { toolExecutionEnvironment } from './goEnv';
 
-// Name of the prompt telemetry command. This is also used to determine if the gopls instance supports telemetry.
-// Exported for testing.
+/**
+ * Name of the prompt telemetry command. This is also used to determine if the
+ * gopls instance supports telemetry.
+ * Exported for testing.
+ */
 export const GOPLS_MAYBE_PROMPT_FOR_TELEMETRY = 'gopls.maybe_prompt_for_telemetry';
 
-// Key for the global state that holds the very first time the telemetry-enabled gopls was observed.
-// Exported for testing.
+/**
+ * Key for the global state that holds the very first time the telemetry-enabled
+ * gopls was observed.
+ * Exported for testing.
+ */
 export const TELEMETRY_START_TIME_KEY = 'telemetryStartTime';
 
-// Run our encode/decode function for the Date object, to be defensive
-// from vscode Memento API behavior change.
-// Exported for testing.
+/**
+ * Run our encode/decode function for the Date object, to be defensive from
+ * vscode Memento API behavior change.
+ * Exported for testing.
+ */
 export function recordTelemetryStartTime(storage: vscode.Memento, date: Date) {
 	storage.update(TELEMETRY_START_TIME_KEY, date.toJSON());
 }
@@ -43,32 +51,57 @@ function readTelemetryStartTime(storage: vscode.Memento): Date | null {
 enum ReporterState {
 	NOT_INITIALIZED,
 	IDLE,
-	STARTING,
 	RUNNING
 }
 
-// exported for testing.
+/**
+ * Manages Go telemetry data and persists them to disk using a storage tool.
+ *
+ * **Usage:**
+ * 1. Call `setTool(tool)` once, before any other methods.
+ * 2. Call `add(key, value)` to add values associated with keys.
+ * 3. Data is automatically flushed to disk periodically.
+ * 4. To force an immediate flush, call `flush(true)`.
+ *
+ * **Example:**
+ * ```typescript
+ * const r = new TelemetryReporter();
+ * r.setTool(vscgo);
+ * r.add("count", 10);
+ * r.add("count", 5);
+ * r.flush(true); // Force a flush
+ * ```
+ *
+ * Exported for testing.
+ */
 export class TelemetryReporter implements vscode.Disposable {
 	private _state = ReporterState.NOT_INITIALIZED;
 	private _counters: { [key: string]: number } = {};
 	private _flushTimer: NodeJS.Timeout | undefined;
 	private _tool = '';
 	constructor(flushIntervalMs = 60_000, private counterFile: string = '') {
 		if (flushIntervalMs > 0) {
-			// periodically call flush.
+			// Periodically call flush.
 			this._flushTimer = setInterval(this.flush.bind(this), flushIntervalMs);
 		}
 	}
 
+	/**
+	 * Initializes the tool.
+	 * This method should be called once. Subsequent calls have no effect.
+	 */
 	public setTool(tool: string) {
-		// allow only once.
+		// Allow only once.
 		if (tool === '' || this._state !== ReporterState.NOT_INITIALIZED) {
 			return;
 		}
 		this._state = ReporterState.IDLE;
 		this._tool = tool;
 	}
 
+	/**
+	 * Adds a numeric value to a counter associated with the given key.
+	 */
 	public add(key: string, value: number) {
 		if (value <= 0) {
 			return;
@@ -77,16 +110,20 @@ export class TelemetryReporter implements vscode.Disposable {
 		this._counters[key] = (this._counters[key] || 0) + value;
 	}
 
-	// flush is called periodically (by the callback set up in the constructor)
-	// or when the extension is deactivated (with force=true).
+	/**
+	 * Flushes Go telemetry data.
+	 * * When `force` is true, telemetry is flushed immediately, bypassing the
+	 * IDLE state check.
+	 * * When `force` is false, telemetry is flushed only if the reporter is IDLE.
+	 */
 	public async flush(force = false) {
 		// If flush runs with force=true, ignore the state and skip state update.
 		if (!force && this._state !== ReporterState.IDLE) {
 			// vscgo is not installed yet or is running. flush next time.
 			return 0;
 		}
 		if (!force) {
-			this._state = ReporterState.STARTING;
+			this._state = ReporterState.RUNNING;
 		}
 		try {
 			await this.writeGoTelemetry();
@@ -142,11 +179,13 @@ export class TelemetryReporter implements vscode.Disposable {
 			clearInterval(this._flushTimer);
 		}
 		this._flushTimer = undefined;
-		await this.flush(true); // flush any remaining data in buffer.
+		await this.flush(true); // Flush any remaining data in buffer.
 	}
 }
 
-// global telemetryReporter instance.
+/**
+ * Global telemetryReporter instance.
+ */
 export const telemetryReporter = new TelemetryReporter();
 
 // TODO(hyangah): consolidate the list of all the telemetries and bucketting functions.
@@ -155,8 +194,10 @@ export function addTelemetryEvent(name: string, count: number) {
 	telemetryReporter.add(name, count);
 }
 
-// Go extension delegates most of the telemetry logic to gopls.
-// TelemetryService provides API to interact with gopls's telemetry.
+/**
+ * Go extension delegates most of the telemetry logic to gopls.
+ * TelemetryService provides API to interact with gopls's telemetry.
+ */
 export class TelemetryService {
 	private active = false;
 	constructor(
@@ -219,8 +260,10 @@ export class TelemetryService {
 	}
 }
 
-// Set telemetry env vars for gopls. See gopls/internal/server/prompt.go
-// TODO(hyangah): add an integration testing after gopls v0.17 becomes available.
+/**
+ * Set telemetry env vars for gopls. See gopls/internal/server/prompt.go
+ * TODO(hyangah): add an integration testing after gopls v0.17 becomes available.
+ */
 export function setTelemetryEnvVars(globalState: vscode.Memento, env: NodeJS.ProcessEnv) {
 	if (!env['GOTELEMETRY_GOPLS_CLIENT_TOKEN']) {
 		env['GOTELEMETRY_GOPLS_CLIENT_TOKEN'] = `${hashMachineID() + 1}`; // [1, 1000]
@@ -234,7 +277,9 @@ export function setTelemetryEnvVars(globalState: vscode.Memento, env: NodeJS.Pro
 	}
 }
 
-// Map vscode.env.machineId to an integer in [0, 1000).
+/**
+ * Map vscode.env.machineId to an integer in [0, 1000).
+ */
 function hashMachineID(salt?: string): number {
 	const hash = createHash('md5').update(`${vscode.env.machineId}${salt}`).digest('hex');
 	return parseInt(hash.substring(0, 8), 16) % 1000;