From 5f0c8d0f108e8baa599397f4c8974becef1bdfac Mon Sep 17 00:00:00 2001
From: Stella Huang <stellahuang@microsoft.com>
Date: Fri, 3 Apr 2026 13:11:15 -0700
Subject: [PATCH 1/5] docs: add @remarks JSDoc sections to EnvironmentManager
 interface methods (Refs #378)

---
 pythonEnvironmentsApi/src/main.ts | 45 +++++++++++++++++++++++++++++++
 src/api.ts                        | 45 +++++++++++++++++++++++++++++++
 2 files changed, 90 insertions(+)

diff --git a/pythonEnvironmentsApi/src/main.ts b/pythonEnvironmentsApi/src/main.ts
index 9032e36a..3057fce8 100644
--- a/pythonEnvironmentsApi/src/main.ts
+++ b/pythonEnvironmentsApi/src/main.ts
@@ -396,6 +396,12 @@ export interface EnvironmentManager {
      * @param scope - The scope within which to create the environment.
      * @param options - Optional parameters for creating the Python environment.
      * @returns A promise that resolves to the created Python environment, or undefined if creation failed.
+     *
+     * @remarks
+     * Called when the user:
+     * - 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.
      */
     create?(scope: CreateEnvironmentScope, options?: CreateEnvironmentOptions): Promise<PythonEnvironment | undefined>;
 
@@ -403,6 +409,10 @@ export interface EnvironmentManager {
      * Removes the specified Python environment.
      * @param environment - The Python environment to remove.
      * @returns A promise that resolves when the environment is removed.
+     *
+     * @remarks
+     * Called when the user right-clicks an environment in the Python Environments tree view and selects
+     * "Delete Environment".
      */
     remove?(environment: PythonEnvironment): Promise<void>;
 
@@ -410,6 +420,9 @@ export interface EnvironmentManager {
      * Refreshes the list of Python environments within the specified scope.
      * @param scope - The scope within which to refresh environments.
      * @returns A promise that resolves when the refresh is complete.
+     *
+     * @remarks
+     * Called when the user clicks the refresh button in the Python Environments view title bar.
      */
     refresh(scope: RefreshEnvironmentsScope): Promise<void>;
 
@@ -417,6 +430,12 @@ export interface EnvironmentManager {
      * Retrieves a list of Python environments within the specified scope.
      * @param scope - The scope within which to retrieve environments.
      * @returns A promise that resolves to an array of Python environments.
+     *
+     * @remarks
+     * Called when:
+     * - The user expands an environment manager node in the Python Environments tree view.
+     * - The user opens the environment picker to select an interpreter.
+     * - Internally after {@link EnvironmentManager.refresh} completes, to count discovered environments.
      */
     getEnvironments(scope: GetEnvironmentsScope): Promise<PythonEnvironment[]>;
 
@@ -430,6 +449,14 @@ export interface EnvironmentManager {
      * @param scope - The scope within which to set the environment.
      * @param environment - The Python environment to set. If undefined, the environment is unset.
      * @returns A promise that resolves when the environment is set.
+     *
+     * @remarks
+     * Called when the user:
+     * - Selects an environment in the environment picker or clicks the checkmark button in the tree view.
+     * - Creates a new environment and the extension auto-selects it.
+     *
+     * 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`).
      */
     set(scope: SetEnvironmentScope, environment?: PythonEnvironment): Promise<void>;
 
@@ -437,6 +464,15 @@ export interface EnvironmentManager {
      * Retrieves the current Python environment within the specified scope.
      * @param scope - The scope within which to retrieve the environment.
      * @returns A promise that resolves to the current Python environment, or undefined if none is set.
+     *
+     * @remarks
+     * Called when:
+     * - The extension starts up, during initial environment selection for each workspace folder and global scope.
+     * - After {@link EnvironmentManager.set}, to confirm the new active environment and fire change events.
+     * - A terminal is opened or a command is run, to determine which Python environment to activate.
+     * - The user runs a Python file ("Run in Terminal", "Run as Task"), to get the interpreter.
+     * - The environment picker needs to display the currently selected (recommended) environment.
+     * - Auto-discovery checks if a local venv already exists for a workspace folder.
      */
     get(scope: GetEnvironmentScope): Promise<PythonEnvironment | undefined>;
 
@@ -456,6 +492,12 @@ export interface EnvironmentManager {
      *
      * @param context - The context for resolving the environment, which can be a {@link PythonEnvironment} or a {@link Uri}.
      * @returns A promise that resolves to the fully detailed {@link PythonEnvironment}, or `undefined` if the environment cannot be resolved.
+     *
+     * @remarks
+     * Called when:
+     * - The user browses for and selects a Python interpreter path via the file picker.
+     * - The user has `python.defaultInterpreterPath` configured and the extension resolves it at startup.
+     * - Before running a Python script ("Run in Terminal", "Run as Task"), to obtain full execution info.
      */
     resolve(context: ResolveEnvironmentContext): Promise<PythonEnvironment | undefined>;
 
@@ -463,6 +505,9 @@ export interface EnvironmentManager {
      * Clears the environment manager's cache.
      *
      * @returns A promise that resolves when the cache is cleared.
+     *
+     * @remarks
+     * Called when the user runs the "Python: Clear Cache" command from the Command Palette.
      */
     clearCache?(): Promise<void>;
 }
diff --git a/src/api.ts b/src/api.ts
index a31a1bd0..9b63573f 100644
--- a/src/api.ts
+++ b/src/api.ts
@@ -390,6 +390,12 @@ export interface EnvironmentManager {
      * @param scope - The scope within which to create the environment.
      * @param options - Optional parameters for creating the Python environment.
      * @returns A promise that resolves to the created Python environment, or undefined if creation failed.
+     *
+     * @remarks
+     * Called when the user:
+     * - 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.
      */
     create?(scope: CreateEnvironmentScope, options?: CreateEnvironmentOptions): Promise<PythonEnvironment | undefined>;
 
@@ -397,6 +403,10 @@ export interface EnvironmentManager {
      * Removes the specified Python environment.
      * @param environment - The Python environment to remove.
      * @returns A promise that resolves when the environment is removed.
+     *
+     * @remarks
+     * Called when the user right-clicks an environment in the Python Environments tree view and selects
+     * "Delete Environment".
      */
     remove?(environment: PythonEnvironment): Promise<void>;
 
@@ -404,6 +414,9 @@ export interface EnvironmentManager {
      * Refreshes the list of Python environments within the specified scope.
      * @param scope - The scope within which to refresh environments.
      * @returns A promise that resolves when the refresh is complete.
+     *
+     * @remarks
+     * Called when the user clicks the refresh button in the Python Environments view title bar.
      */
     refresh(scope: RefreshEnvironmentsScope): Promise<void>;
 
@@ -411,6 +424,12 @@ export interface EnvironmentManager {
      * Retrieves a list of Python environments within the specified scope.
      * @param scope - The scope within which to retrieve environments.
      * @returns A promise that resolves to an array of Python environments.
+     *
+     * @remarks
+     * Called when:
+     * - The user expands an environment manager node in the Python Environments tree view.
+     * - The user opens the environment picker to select an interpreter.
+     * - Internally after {@link EnvironmentManager.refresh} completes, to count discovered environments.
      */
     getEnvironments(scope: GetEnvironmentsScope): Promise<PythonEnvironment[]>;
 
@@ -424,6 +443,14 @@ export interface EnvironmentManager {
      * @param scope - The scope within which to set the environment.
      * @param environment - The Python environment to set. If undefined, the environment is unset.
      * @returns A promise that resolves when the environment is set.
+     *
+     * @remarks
+     * Called when the user:
+     * - Selects an environment in the environment picker or clicks the checkmark button in the tree view.
+     * - Creates a new environment and the extension auto-selects it.
+     *
+     * 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`).
      */
     set(scope: SetEnvironmentScope, environment?: PythonEnvironment): Promise<void>;
 
@@ -431,6 +458,15 @@ export interface EnvironmentManager {
      * Retrieves the current Python environment within the specified scope.
      * @param scope - The scope within which to retrieve the environment.
      * @returns A promise that resolves to the current Python environment, or undefined if none is set.
+     *
+     * @remarks
+     * Called when:
+     * - The extension starts up, during initial environment selection for each workspace folder and global scope.
+     * - After {@link EnvironmentManager.set}, to confirm the new active environment and fire change events.
+     * - A terminal is opened or a command is run, to determine which Python environment to activate.
+     * - The user runs a Python file ("Run in Terminal", "Run as Task"), to get the interpreter.
+     * - The environment picker needs to display the currently selected (recommended) environment.
+     * - Auto-discovery checks if a local venv already exists for a workspace folder.
      */
     get(scope: GetEnvironmentScope): Promise<PythonEnvironment | undefined>;
 
@@ -450,6 +486,12 @@ export interface EnvironmentManager {
      *
      * @param context - The context for resolving the environment, which can be a {@link PythonEnvironment} or a {@link Uri}.
      * @returns A promise that resolves to the fully detailed {@link PythonEnvironment}, or `undefined` if the environment cannot be resolved.
+     *
+     * @remarks
+     * Called when:
+     * - The user browses for and selects a Python interpreter path via the file picker.
+     * - The user has `python.defaultInterpreterPath` configured and the extension resolves it at startup.
+     * - Before running a Python script ("Run in Terminal", "Run as Task"), to obtain full execution info.
      */
     resolve(context: ResolveEnvironmentContext): Promise<PythonEnvironment | undefined>;
 
@@ -457,6 +499,9 @@ export interface EnvironmentManager {
      * Clears the environment manager's cache.
      *
      * @returns A promise that resolves when the cache is cleared.
+     *
+     * @remarks
+     * Called when the user runs the "Python: Clear Cache" command from the Command Palette.
      */
     clearCache?(): Promise<void>;
 }

From 7b7cc58149c669b8bb659777787c3d50317c4930 Mon Sep 17 00:00:00 2001
From: Stella Huang <100439259+StellaHuang95@users.noreply.github.com>
Date: Wed, 15 Apr 2026 12:57:26 -0700
Subject: [PATCH 2/5] Update src/api.ts

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 src/api.ts | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/api.ts b/src/api.ts
index 9b63573f..90f2d884 100644
--- a/src/api.ts
+++ b/src/api.ts
@@ -393,9 +393,9 @@ export interface EnvironmentManager {
      *
      * @remarks
      * Called when the user:
-     * - 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.
      */
     create?(scope: CreateEnvironmentScope, options?: CreateEnvironmentOptions): Promise<PythonEnvironment | undefined>;
 

From cffd0cf8ce6b7dc49d92a4e1251f762fc7314244 Mon Sep 17 00:00:00 2001
From: Stella Huang <100439259+StellaHuang95@users.noreply.github.com>
Date: Wed, 15 Apr 2026 12:59:04 -0700
Subject: [PATCH 3/5] Update pythonEnvironmentsApi/src/main.ts

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 pythonEnvironmentsApi/src/main.ts | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/pythonEnvironmentsApi/src/main.ts b/pythonEnvironmentsApi/src/main.ts
index 3057fce8..3a81f5a8 100644
--- a/pythonEnvironmentsApi/src/main.ts
+++ b/pythonEnvironmentsApi/src/main.ts
@@ -455,8 +455,12 @@ export interface EnvironmentManager {
      * - Selects an environment in the environment picker or clicks the checkmark button in the tree view.
      * - Creates a new environment and the extension auto-selects it.
      *
-     * 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`).
      */
     set(scope: SetEnvironmentScope, environment?: PythonEnvironment): Promise<void>;
 

From 325186195b23411ce838ee7a39bf9efefe1abb2d Mon Sep 17 00:00:00 2001
From: Stella Huang <stellahuang@microsoft.com>
Date: Wed, 15 Apr 2026 13:10:17 -0700
Subject: [PATCH 4/5] sync apis

---
 pythonEnvironmentsApi/src/main.ts | 6 +++---
 src/api.ts                        | 8 ++++++--
 2 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/pythonEnvironmentsApi/src/main.ts b/pythonEnvironmentsApi/src/main.ts
index 3a81f5a8..2e698e7d 100644
--- a/pythonEnvironmentsApi/src/main.ts
+++ b/pythonEnvironmentsApi/src/main.ts
@@ -399,9 +399,9 @@ export interface EnvironmentManager {
      *
      * @remarks
      * Called when the user:
-     * - 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.
      */
     create?(scope: CreateEnvironmentScope, options?: CreateEnvironmentOptions): Promise<PythonEnvironment | undefined>;
 
diff --git a/src/api.ts b/src/api.ts
index 90f2d884..4bc2445b 100644
--- a/src/api.ts
+++ b/src/api.ts
@@ -449,8 +449,12 @@ export interface EnvironmentManager {
      * - Selects an environment in the environment picker or clicks the checkmark button in the tree view.
      * - Creates a new environment and the extension auto-selects it.
      *
-     * 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`).
      */
     set(scope: SetEnvironmentScope, environment?: PythonEnvironment): Promise<void>;
 

From 7de08fb2f609465c739e9bfd0d3c4080e6cdaa1f Mon Sep 17 00:00:00 2001
From: Stella Huang <stellahuang@microsoft.com>
Date: Thu, 16 Apr 2026 12:59:54 -0700
Subject: [PATCH 5/5] address feedback

---
 pythonEnvironmentsApi/src/main.ts | 68 ++++++++++++++++---------------
 src/api.ts                        | 68 ++++++++++++++++---------------
 2 files changed, 72 insertions(+), 64 deletions(-)

diff --git a/pythonEnvironmentsApi/src/main.ts b/pythonEnvironmentsApi/src/main.ts
index 2e698e7d..4f3b0e46 100644
--- a/pythonEnvironmentsApi/src/main.ts
+++ b/pythonEnvironmentsApi/src/main.ts
@@ -343,6 +343,14 @@ export interface QuickCreateConfig {
 
 /**
  * Interface representing an environment manager.
+ *
+ * @remarks
+ * Methods on this interface are invoked both by the Python Environments extension itself
+ * (in response to UI actions, startup, terminal activation, script execution, and so on)
+ * and directly by other extensions that consume the published API. Any "called when…"
+ * notes on individual methods list representative triggers only — they are not
+ * exhaustive, and the precise set of call sites may evolve over time. Implementations
+ * should focus on the documented contract rather than any specific caller.
  */
 export interface EnvironmentManager {
     /**
@@ -398,10 +406,9 @@ export interface EnvironmentManager {
      * @returns A promise that resolves to the created Python environment, or undefined if creation failed.
      *
      * @remarks
-     * Called when the user:
-     * - 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.
+     * Invoked when an environment of this manager's type should be created for the given
+     * scope. Typical triggers include user-initiated environment-creation flows and
+     * programmatic creation via the API.
      */
     create?(scope: CreateEnvironmentScope, options?: CreateEnvironmentOptions): Promise<PythonEnvironment | undefined>;
 
@@ -411,8 +418,8 @@ export interface EnvironmentManager {
      * @returns A promise that resolves when the environment is removed.
      *
      * @remarks
-     * Called when the user right-clicks an environment in the Python Environments tree view and selects
-     * "Delete Environment".
+     * Invoked to delete the given environment. Typical triggers include an explicit user
+     * action (such as a "Delete Environment" command) and programmatic removal via the API.
      */
     remove?(environment: PythonEnvironment): Promise<void>;
 
@@ -422,7 +429,8 @@ export interface EnvironmentManager {
      * @returns A promise that resolves when the refresh is complete.
      *
      * @remarks
-     * Called when the user clicks the refresh button in the Python Environments view title bar.
+     * Forces the manager to re-discover environments for the given scope. Typically
+     * triggered by an explicit user "refresh" action.
      */
     refresh(scope: RefreshEnvironmentsScope): Promise<void>;
 
@@ -432,10 +440,8 @@ export interface EnvironmentManager {
      * @returns A promise that resolves to an array of Python environments.
      *
      * @remarks
-     * Called when:
-     * - The user expands an environment manager node in the Python Environments tree view.
-     * - The user opens the environment picker to select an interpreter.
-     * - Internally after {@link EnvironmentManager.refresh} completes, to count discovered environments.
+     * Returns the environments known to this manager for the given scope. Called
+     * frequently by UI surfaces (tree views, pickers) and by other consumers of the API.
      */
     getEnvironments(scope: GetEnvironmentsScope): Promise<PythonEnvironment[]>;
 
@@ -451,16 +457,12 @@ export interface EnvironmentManager {
      * @returns A promise that resolves when the environment is set.
      *
      * @remarks
-     * Called when the user:
-     * - Selects an environment in the environment picker or clicks the checkmark button in the tree view.
-     * - Creates a new environment and the extension auto-selects it.
+     * Invoked when the active environment for the given scope should change — for example
+     * after the user selects an environment in a picker, after a newly created environment
+     * is auto-selected, or programmatically via the API.
      *
-     * 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`).
+     * Also invoked at extension startup to rehydrate the active environment from
+     * persisted state.
      */
     set(scope: SetEnvironmentScope, environment?: PythonEnvironment): Promise<void>;
 
@@ -470,13 +472,10 @@ export interface EnvironmentManager {
      * @returns A promise that resolves to the current Python environment, or undefined if none is set.
      *
      * @remarks
-     * Called when:
-     * - The extension starts up, during initial environment selection for each workspace folder and global scope.
-     * - After {@link EnvironmentManager.set}, to confirm the new active environment and fire change events.
-     * - A terminal is opened or a command is run, to determine which Python environment to activate.
-     * - The user runs a Python file ("Run in Terminal", "Run as Task"), to get the interpreter.
-     * - The environment picker needs to display the currently selected (recommended) environment.
-     * - Auto-discovery checks if a local venv already exists for a workspace folder.
+     * Returns the currently active environment for the given scope, or `undefined` if
+     * none is selected. Called very frequently — at startup, after {@link set}, when a
+     * terminal is opened, before running Python, by UI surfaces that display the active
+     * interpreter, and by other extensions consuming the API.
      */
     get(scope: GetEnvironmentScope): Promise<PythonEnvironment | undefined>;
 
@@ -498,10 +497,12 @@ export interface EnvironmentManager {
      * @returns A promise that resolves to the fully detailed {@link PythonEnvironment}, or `undefined` if the environment cannot be resolved.
      *
      * @remarks
-     * Called when:
-     * - The user browses for and selects a Python interpreter path via the file picker.
-     * - The user has `python.defaultInterpreterPath` configured and the extension resolves it at startup.
-     * - Before running a Python script ("Run in Terminal", "Run as Task"), to obtain full execution info.
+     * Called to turn a lightly-populated {@link PythonEnvironment} or a {@link Uri}
+     * pointing at an interpreter or environment folder into a fully-populated
+     * {@link PythonEnvironment} with complete {@link PythonEnvironment.execInfo}. Typical
+     * triggers include the user manually selecting an interpreter path, resolving
+     * `python.defaultInterpreterPath` at startup, and populating execution details before
+     * launching Python.
      */
     resolve(context: ResolveEnvironmentContext): Promise<PythonEnvironment | undefined>;
 
@@ -511,7 +512,10 @@ export interface EnvironmentManager {
      * @returns A promise that resolves when the cache is cleared.
      *
      * @remarks
-     * Called when the user runs the "Python: Clear Cache" command from the Command Palette.
+     * Drops any cached environment data held by the manager so that subsequent calls to
+     * {@link EnvironmentManager.getEnvironments} or {@link EnvironmentManager.get}
+     * re-discover state from disk. Typically triggered by an explicit user "clear cache"
+     * action.
      */
     clearCache?(): Promise<void>;
 }
diff --git a/src/api.ts b/src/api.ts
index 4bc2445b..0286f017 100644
--- a/src/api.ts
+++ b/src/api.ts
@@ -337,6 +337,14 @@ export interface QuickCreateConfig {
 
 /**
  * Interface representing an environment manager.
+ *
+ * @remarks
+ * Methods on this interface are invoked both by the Python Environments extension itself
+ * (in response to UI actions, startup, terminal activation, script execution, and so on)
+ * and directly by other extensions that consume the published API. Any "called when…"
+ * notes on individual methods list representative triggers only — they are not
+ * exhaustive, and the precise set of call sites may evolve over time. Implementations
+ * should focus on the documented contract rather than any specific caller.
  */
 export interface EnvironmentManager {
     /**
@@ -392,10 +400,9 @@ export interface EnvironmentManager {
      * @returns A promise that resolves to the created Python environment, or undefined if creation failed.
      *
      * @remarks
-     * Called when the user:
-     * - 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.
+     * Invoked when an environment of this manager's type should be created for the given
+     * scope. Typical triggers include user-initiated environment-creation flows and
+     * programmatic creation via the API.
      */
     create?(scope: CreateEnvironmentScope, options?: CreateEnvironmentOptions): Promise<PythonEnvironment | undefined>;
 
@@ -405,8 +412,8 @@ export interface EnvironmentManager {
      * @returns A promise that resolves when the environment is removed.
      *
      * @remarks
-     * Called when the user right-clicks an environment in the Python Environments tree view and selects
-     * "Delete Environment".
+     * Invoked to delete the given environment. Typical triggers include an explicit user
+     * action (such as a "Delete Environment" command) and programmatic removal via the API.
      */
     remove?(environment: PythonEnvironment): Promise<void>;
 
@@ -416,7 +423,8 @@ export interface EnvironmentManager {
      * @returns A promise that resolves when the refresh is complete.
      *
      * @remarks
-     * Called when the user clicks the refresh button in the Python Environments view title bar.
+     * Forces the manager to re-discover environments for the given scope. Typically
+     * triggered by an explicit user "refresh" action.
      */
     refresh(scope: RefreshEnvironmentsScope): Promise<void>;
 
@@ -426,10 +434,8 @@ export interface EnvironmentManager {
      * @returns A promise that resolves to an array of Python environments.
      *
      * @remarks
-     * Called when:
-     * - The user expands an environment manager node in the Python Environments tree view.
-     * - The user opens the environment picker to select an interpreter.
-     * - Internally after {@link EnvironmentManager.refresh} completes, to count discovered environments.
+     * Returns the environments known to this manager for the given scope. Called
+     * frequently by UI surfaces (tree views, pickers) and by other consumers of the API.
      */
     getEnvironments(scope: GetEnvironmentsScope): Promise<PythonEnvironment[]>;
 
@@ -445,16 +451,12 @@ export interface EnvironmentManager {
      * @returns A promise that resolves when the environment is set.
      *
      * @remarks
-     * Called when the user:
-     * - Selects an environment in the environment picker or clicks the checkmark button in the tree view.
-     * - Creates a new environment and the extension auto-selects it.
+     * Invoked when the active environment for the given scope should change — for example
+     * after the user selects an environment in a picker, after a newly created environment
+     * is auto-selected, or programmatically via the API.
      *
-     * 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`).
+     * Also invoked at extension startup to rehydrate the active environment from
+     * persisted state.
      */
     set(scope: SetEnvironmentScope, environment?: PythonEnvironment): Promise<void>;
 
@@ -464,13 +466,10 @@ export interface EnvironmentManager {
      * @returns A promise that resolves to the current Python environment, or undefined if none is set.
      *
      * @remarks
-     * Called when:
-     * - The extension starts up, during initial environment selection for each workspace folder and global scope.
-     * - After {@link EnvironmentManager.set}, to confirm the new active environment and fire change events.
-     * - A terminal is opened or a command is run, to determine which Python environment to activate.
-     * - The user runs a Python file ("Run in Terminal", "Run as Task"), to get the interpreter.
-     * - The environment picker needs to display the currently selected (recommended) environment.
-     * - Auto-discovery checks if a local venv already exists for a workspace folder.
+     * Returns the currently active environment for the given scope, or `undefined` if
+     * none is selected. Called very frequently — at startup, after {@link set}, when a
+     * terminal is opened, before running Python, by UI surfaces that display the active
+     * interpreter, and by other extensions consuming the API.
      */
     get(scope: GetEnvironmentScope): Promise<PythonEnvironment | undefined>;
 
@@ -492,10 +491,12 @@ export interface EnvironmentManager {
      * @returns A promise that resolves to the fully detailed {@link PythonEnvironment}, or `undefined` if the environment cannot be resolved.
      *
      * @remarks
-     * Called when:
-     * - The user browses for and selects a Python interpreter path via the file picker.
-     * - The user has `python.defaultInterpreterPath` configured and the extension resolves it at startup.
-     * - Before running a Python script ("Run in Terminal", "Run as Task"), to obtain full execution info.
+     * Called to turn a lightly-populated {@link PythonEnvironment} or a {@link Uri}
+     * pointing at an interpreter or environment folder into a fully-populated
+     * {@link PythonEnvironment} with complete {@link PythonEnvironment.execInfo}. Typical
+     * triggers include the user manually selecting an interpreter path, resolving
+     * `python.defaultInterpreterPath` at startup, and populating execution details before
+     * launching Python.
      */
     resolve(context: ResolveEnvironmentContext): Promise<PythonEnvironment | undefined>;
 
@@ -505,7 +506,10 @@ export interface EnvironmentManager {
      * @returns A promise that resolves when the cache is cleared.
      *
      * @remarks
-     * Called when the user runs the "Python: Clear Cache" command from the Command Palette.
+     * Drops any cached environment data held by the manager so that subsequent calls to
+     * {@link EnvironmentManager.getEnvironments} or {@link EnvironmentManager.get}
+     * re-discover state from disk. Typically triggered by an explicit user "clear cache"
+     * action.
      */
     clearCache?(): Promise<void>;
 }