docs: add comprehensive JSDoc to critical public APIs

Add detailed JSDoc documentation to the most important public APIs
to improve developer experience, enable better IDE IntelliSense, and
enhance AI-assisted development with tools like GitHub Copilot and Cursor.

Functions documented:

goMain.ts:
- activate(): Extension entry point with full activation sequence
- deactivate(): Extension cleanup with all shutdown operations

util.ts:
- getBinPath(): Primary tool path resolution function (used 50+ times)
- getBinPathWithExplanation(): Tool path with diagnostic info
- getFileArchive(): Document serialization for Go tools
- handleDiagnosticErrors(): Central diagnostic display pipeline

goLanguageServer.ts:
- buildLanguageClient(): LSP client construction and configuration
- buildLanguageServerConfig(): Language server config builder

Documentation includes:
- Detailed parameter descriptions with types
- Return value specifications
- Usage examples with realistic code
- Implementation details and search order
- Feature lists and configuration options
- Cross-references to related functions

Benefits:
- Better IntelliSense autocomplete in VS Code
- Improved API discoverability for contributors
- Enhanced context for AI coding assistants
- Self-documenting codebase reduces onboarding time
- Clearer understanding of function contracts

Related to medium-priority code quality improvements.

Author: claude

extension/src/goMain.ts

@@ -83,6 +83,29 @@ interface ExtensionTestAPI {
 	globalState: vscode.Memento;
 }
 
+/**
+ * Extension activation entry point called by VS Code when the Go extension loads.
+ * This is the main initialization function that sets up all Go development features.
+ *
+ * Activation sequence:
+ * 1. Initialize global and workspace state
+ * 2. Configure GOROOT and environment variables
+ * 3. Build and install vscgo helper tool
+ * 4. Register all extension commands
+ * 5. Set up language features (code lens, formatting, testing, etc.)
+ * 6. Start gopls language server (if enabled)
+ * 7. Install missing/outdated Go tools
+ * 8. Configure telemetry and surveys
+ *
+ * @param ctx - VS Code extension context providing subscriptions, storage, and paths
+ * @returns ExtensionAPI for production use or ExtensionTestAPI for testing
+ *
+ * @example
+ * // Called automatically by VS Code, not by user code
+ * // Returns API that can be accessed by other extensions via:
+ * const goExt = vscode.extensions.getExtension('golang.go');
+ * const api = await goExt?.activate();
+ */
 export async function activate(ctx: vscode.ExtensionContext): Promise<ExtensionAPI | ExtensionTestAPI | undefined> {
 	if (process.env['VSCODE_GO_IN_TEST'] === '1') {
 		// TODO: VSCODE_GO_IN_TEST was introduced long before we learned about
@@ -240,6 +263,26 @@ export async function activate(ctx: vscode.ExtensionContext): Promise<ExtensionA
 	return extensionAPI;
 }
 
+/**
+ * Extension deactivation called by VS Code when the extension is being unloaded.
+ * Performs cleanup to ensure no resources are leaked and all background processes are stopped.
+ *
+ * Cleanup operations (all run in parallel):
+ * - Stop gopls language server and wait for graceful shutdown
+ * - Cancel any running test sessions
+ * - Kill any active pprof profiling processes
+ * - Clean up temporary directories and files
+ * - Dispose status bar items
+ * - Flush and dispose telemetry reporter
+ *
+ * @returns Promise that resolves when all cleanup is complete
+ *
+ * @example
+ * // Called automatically by VS Code when:
+ * // - Extension is disabled
+ * // - Extension is being updated
+ * // - VS Code is shutting down
+ */
 export function deactivate() {
 	return Promise.all([
 		goCtx.languageClient?.stop(),

extension/src/language/goLanguageServer.ts

@@ -388,8 +388,27 @@ type VulncheckEvent = {
 	message?: string;
 };
 
-// buildLanguageClient returns a language client built using the given language server config.
-// The returned language client need to be started before use.
+/**
+ * Builds a VS Code Language Server Protocol (LSP) client for gopls.
+ * The returned client is configured but not started - caller must call .start() on it.
+ *
+ * This function sets up:
+ * - Output channels for server logs and traces
+ * - Language server executable options (path, flags, environment)
+ * - Client options (document selectors, middleware, synchronization)
+ * - Progress handlers for gopls operations
+ * - Command execution middleware
+ * - Configuration synchronization with gopls
+ *
+ * @param goCtx - Go extension context containing output channels and state
+ * @param cfg - Language server configuration with path, flags, and features
+ * @returns Configured GoLanguageClient instance ready to be started
+ *
+ * @example
+ * const cfg = await buildLanguageServerConfig(getGoConfig());
+ * const client = await buildLanguageClient(goCtx, cfg);
+ * await client.start(); // Start the language server
+ */
 export async function buildLanguageClient(
 	goCtx: GoExtensionContext,
 	cfg: LanguageServerConfig
@@ -1031,6 +1050,29 @@ function createBenchmarkCodeLens(lens: vscode.CodeLens): vscode.CodeLens[] {
 	];
 }
 
+/**
+ * Builds the configuration object for the Go language server (gopls).
+ * This function locates gopls, validates it exists, and constructs the config needed to start it.
+ *
+ * Configuration includes:
+ * - Server executable path (from go.languageServerPath setting or auto-detected)
+ * - Server command-line flags (from go.languageServerFlags)
+ * - Environment variables for gopls process
+ * - Custom formatter (if go.formatTool is set to override gopls formatting)
+ * - Update check preferences (from go.toolsManagement.checkForUpdates)
+ * - Server version and modification time (for tracking updates)
+ *
+ * @param goConfig - VS Code workspace configuration for the Go extension
+ * @returns LanguageServerConfig object, with `enabled: false` if gopls is disabled or not found
+ *
+ * @example
+ * const goConfig = getGoConfig();
+ * const cfg = await buildLanguageServerConfig(goConfig);
+ * if (cfg.enabled) {
+ *   console.log(`Found gopls at: ${cfg.path}`);
+ *   const client = await buildLanguageClient(goCtx, cfg);
+ * }
+ */
 export async function buildLanguageServerConfig(
 	goConfig: vscode.WorkspaceConfiguration
 ): Promise<LanguageServerConfig> {

extension/src/util.ts

@@ -308,14 +308,48 @@ function resolveToolsGopath(): string {
 	return toolsGopathForWorkspace;
 }
 
-// getBinPath returns the path to the tool.
+/**
+ * Returns the absolute path to a Go tool's executable.
+ * This is the primary function used throughout the extension to locate Go tools.
+ *
+ * Search order:
+ * 1. Alternate tools configured in go.alternateTools
+ * 2. GOBIN environment variable
+ * 3. Configured toolsGopath (go.toolsGopath setting)
+ * 4. Current workspace GOPATH
+ * 5. GOROOT/bin (for go, gofmt, godoc)
+ * 6. PATH environment variable
+ * 7. Default system locations (e.g., /usr/local/go/bin)
+ *
+ * @param tool - Name of the tool (e.g., 'gopls', 'dlv', 'staticcheck')
+ * @param useCache - Whether to use cached tool paths (default: true)
+ * @returns Absolute path to the tool executable, or just the tool name if not found
+ *
+ * @example
+ * const goplsPath = getBinPath('gopls'); // Returns '/Users/me/go/bin/gopls'
+ * const goPath = getBinPath('go'); // Returns '/usr/local/go/bin/go'
+ */
 export function getBinPath(tool: string, useCache = true): string {
 	const r = getBinPathWithExplanation(tool, useCache);
 	return r.binPath;
 }
 
-// getBinPathWithExplanation returns the path to the tool, and the explanation on why
-// the path was chosen. See getBinPathWithPreferredGopathGorootWithExplanation for details.
+/**
+ * Returns the absolute path to a Go tool's executable along with an explanation
+ * of where the path was found. Useful for diagnostics and troubleshooting.
+ *
+ * @param tool - Name of the tool (e.g., 'gopls', 'dlv', 'staticcheck')
+ * @param useCache - Whether to use cached tool paths (default: true)
+ * @param uri - Optional workspace URI for multi-root workspace support
+ * @returns Object containing the tool path and optional explanation
+ *   - binPath: Absolute path to the tool executable
+ *   - why: Optional explanation ('gobin', 'gopath', 'goroot', 'path', 'alternateTool', 'cached', 'default')
+ *
+ * @example
+ * const result = getBinPathWithExplanation('gopls');
+ * console.log(`Found gopls at ${result.binPath} (source: ${result.why})`);
+ * // Output: "Found gopls at /Users/me/go/bin/gopls (source: gobin)"
+ */
 export function getBinPathWithExplanation(
 	tool: string,
 	useCache = true,
@@ -342,6 +376,19 @@ export function getBinPathWithExplanation(
 	);
 }
 
+/**
+ * Serializes a VS Code document into the archive format expected by Go tools.
+ * This format is used to pass modified/unsaved file contents to tools like gopls and goimports.
+ *
+ * Format: `filename\nbytelength\ncontents`
+ *
+ * @param document - The VS Code text document to serialize
+ * @returns Serialized document in archive format
+ *
+ * @example
+ * const archive = getFileArchive(document);
+ * // Returns: "/path/to/file.go\n1234\npackage main..."
+ */
 export function getFileArchive(document: vscode.TextDocument): string {
 	const fileContents = document.getText();
 	return document.fileName + '\n' + Buffer.byteLength(fileContents, 'utf8') + '\n' + fileContents;
@@ -640,6 +687,28 @@ export function runTool(
 	});
 }
 
+/**
+ * Converts tool output errors into VS Code diagnostics and displays them in the Problems panel.
+ * This is the central function for surfacing errors from Go tools (gopls, staticcheck, golint, etc.)
+ * to the VS Code UI.
+ *
+ * Features:
+ * - Clears existing diagnostics before adding new ones
+ * - Maps error positions to VS Code ranges using token-based column calculation
+ * - Groups diagnostics by file for efficient display
+ * - Handles both open and closed files
+ * - Filters out diagnostics that overlap with gopls diagnostics (if gopls is enabled)
+ *
+ * @param goCtx - Go extension context for accessing configuration
+ * @param document - Optional document that triggered the check (for optimization)
+ * @param errors - Array of check results from Go tools
+ * @param diagnosticCollection - VS Code diagnostic collection to update (e.g., 'go-lint', 'go-vet')
+ * @param diagnosticSource - Optional source label for the diagnostics (e.g., 'staticcheck', 'golint')
+ *
+ * @example
+ * const errors = await runGoVet(document);
+ * handleDiagnosticErrors(goCtx, document, errors, vetDiagnosticCollection, 'go-vet');
+ */
 export function handleDiagnosticErrors(
 	goCtx: GoExtensionContext,
 	document: vscode.TextDocument | undefined,