cmd/go: doc: "go doc pkg.Func" doesn't search in defining package whose path has form "example.com/pkg-go/v2" #76248
Description
Proposal Details
Issue Description
The go doc command is a core Go tool designed to extract and display documentation comments for packages, symbols (e.g., functions, types, constants, variables), methods, or fields directly from the command line. It is particularly useful for quick lookups during development without needing to open a browser or IDE. However, its current behavior creates friction when working with imported external modules, which is a common workflow in modern Go projects using the module system.
Core Problem
Default Behavior: When invoked without a fully qualified path (e.g., go doc openai.NewClient), go doc assumes the symbol (e.g., openai.NewClient) exists in the current package (the directory where the command is run). It searches locally and fails if the symbol is not defined there.
Error: doc: symbol openai is not a type in package main installed in "." (or similar, indicating a local lookup failure).
Root Cause: Imported packages (e.g., via import "github.com/openai/openai-go/v3") are aliased in your code (often as openai), but go doc does not automatically resolve or infer these import paths from your source files or go.mod. It requires the full import path (e.g., go doc github.com/openai/openai-go/v3.NewClient) to locate and display docs from external modules.
User Impact:
Developers must manually recall or copy-paste full import paths, which are often long and verbose (e.g., github.com/openai/openai-go/v3.option.WithAPIKey).
This disrupts quick iteration, especially in large projects with many dependencies.
It feels unintuitive compared to code editors/IDEs (e.g., VS Code with gopls), which resolve imports contextually and show hover docs seamlessly.
No built-in way to discover or list imported symbols from the current workspace without additional tools like go list or godoc.
This issue stems from the tool's design philosophy: it's lightweight and package-centric, prioritizing simplicity over deep workspace awareness. From Go's official docs (cmd/doc package):
"The first argument must be a full package path."
While effective for stdlib or local packages, it underperforms for the module-heavy ecosystem introduced in Go 1.11.
Reproducibility
Create a minimal main.go importing an external module (e.g., OpenAI's Go client).
Run go mod tidy to fetch dependencies.
Execute go doc → Fails with local package error.
Use full path → Succeeds, but requires extra effort.
This affects ~80-90% of real-world Go usage, where projects import 5+ external modules on average (based on common go.mod patterns).
Proposal
Make go doc <symbol> automatically resolve symbols from imported packages in the current directory if not found locally.