docs: add @remarks to EnvironmentManager interface documenting when each method is called

[StellaHuang95]

Summary

Adds @remarks JSDoc sections to all methods on the EnvironmentManager interface, documenting which user actions or internal events trigger each method. Changes are documentation-only — no functional changes.

Motivation

Raised in #378: third-party extension authors implementing EnvironmentManager know what each method does (the existing JSDoc covers that), but not when or why it gets called. For example, get() is described as "retrieves the current Python environment" — but there's no mention that it's called at extension startup, during terminal activation, before script execution, etc.

This makes it hard for authors to reason about their implementation. They end up guessing at lifecycle behavior, which leads to bugs (e.g., not caching in get() because they didn't realize it's called frequently).

What's added

@remarks sections on 8 methods of EnvironmentManager in both src/api.ts and pythonEnvironmentsApi/src/main.ts:

Method	Trigger summary
create	"Create Environment" command, "+" button in tree view, new package project wizard
remove	Right-click → "Delete Environment" in tree view
refresh	Refresh button in the Python Environments view title bar
getEnvironments	Tree view expansion, environment picker, internally after refresh
set	Environment picker selection, checkmark button in tree view, auto-select after create, startup caching, project removal
get	Startup, after set, terminal activation, script execution, picker display, auto-discovery
resolve	File picker interpreter selection, defaultInterpreterPath resolution, pre-run resolution
clearCache	"Python: Clear Cache" command

Each remark was verified by tracing every call site through InternalEnvironmentManager → envManagers.ts → envCommands.ts → extension.ts command registrations and package.json menu contributions.

Who this helps

Extension authors building environment managers for tools like Hatch, Pixi, uv, etc. They can now hover over any EnvironmentManager method in their IDE and see exactly what user actions will invoke it, making implementation decisions much clearer.

Files changed

• src/api.ts — internal API copy (+45 lines, documentation only)
• pythonEnvironmentsApi/src/main.ts — published API package (+45 lines, documentation only)

Refs #378

[eleanorjboyd]

will review - sorry for the delay

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds @remarks documentation to the EnvironmentManager interface to clarify which user actions / internal events trigger each method, helping third-party implementers understand lifecycle and call frequency.

Changes:

• Added @remarks sections for 8 EnvironmentManager methods describing triggering UI actions and internal flows.
• Mirrored the same documentation in both the internal (src/api.ts) and published (pythonEnvironmentsApi/src/main.ts) API surfaces.

Show a summary per file

File	Description
src/api.ts	Adds @remarks to EnvironmentManager methods documenting when each is invoked.
pythonEnvironmentsApi/src/main.ts	Mirrors the same @remarks additions for the published API package.

Copilot's findings

• Files reviewed: 2/2 changed files
• Comments generated: 3

[Copilot]

The new remarks rely on exact UI labels/symbols (e.g., command palette text, "+" button) which can change over time and may be localized. Consider referencing stable identifiers instead (e.g., command IDs like python.createEnvironment, view IDs, or contribution points such as package.json command/menu entries) and phrasing UI triggers more generically (e.g., “the Create Environment command” / “the add-environment action in the Python Environments view”). This will make the docs more resilient and less likely to become stale.

Suggested change

	* - Runs the "Python: Create Environment" command (which prompts for a manager to use).
	* - Clicks the "+" button on an environment manager in the Python Environments view.
	* - Creates a new environment as part of the new Python package project creation wizard.
	* - Invokes the `python.createEnvironment` command (which prompts for a manager to use).
	* - Uses the add-environment action for an environment manager in the Python Environments view.
	* - Creates a new environment as part of a Python package project creation flow.

[Copilot]

The remark “called…to cache the active environment” could be read as suggesting set() is used for caching rather than state changes. To reduce ambiguity for implementers, consider clarifying expected semantics at startup (e.g., that set() may be invoked with the already-persisted/previously-selected environment and should be treated as idempotent, potentially firing change events only when the selection actually changes). This helps implementers avoid doing unnecessary work or producing side effects on startup.

Suggested change

	* Also called at extension startup during initial environment selection to cache the active
	* environment, and when a Python project is removed (with `environment` set to `undefined`).
	* Also called at extension startup during initial environment selection to initialize or
	* reconcile the active environment state. This startup call may pass the already-persisted or
	* previously-selected environment; implementations should treat it as idempotent and avoid
	* unnecessary work or side effects, including firing change events, unless the selected
	* environment actually changes. Also called when a Python project is removed (with
	* `environment` set to `undefined`).

[Copilot]

This PR intentionally duplicates substantial documentation across src/api.ts and pythonEnvironmentsApi/src/main.ts. Since these two interface definitions must stay in sync, the added @remarks increases the risk of divergence over time. If feasible in this repo, consider centralizing the EnvironmentManager type (or generating the published API from the internal source) so the docs live in a single place and are re-exported/shared, reducing future maintenance burden.