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

[StellaHuang95]

done addressing the comments

[eleanorjboyd]

this can also be called by another extension or elsewhere in the extension tho? I am worried about tying these so closely to their current implementations they will become stale quickly and then lead future agents astray

[StellaHuang95]

That's good point. You're right that (a) these methods are public API that other extensions can call directly, and (b) enumerating current UI call sites will drift as the extension evolves. So here's the improvements I made:

Added an interface-level @remarks on EnvironmentManager noting that the methods are called by both this extension and external API consumers, and that any trigger notes on individual methods are representative, not exhaustive.

Replaced the per-method "called when the user clicks X" bullet lists with a short description of what the method is for, followed by "typical triggers include…" framed as examples rather than a spec. No specific buttons, menus, or command IDs are named, so the docs stay accurate if the UI is rewired. Let me know if you have any more feedback. Thanks for reviewing!