sync apis

Author: StellaHuang95

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>;
 

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>;