updates to project manager docs and comments (#387)

added a doc explaining how the project technical design works
add comments and docstrings for clarity

Author: eleanorjboyd

docs/projects-api-reference.md

@@ -0,0 +1,75 @@
+# Python Projects API Reference
+
+## Modifying Projects
+This is how the projects API is designed with the different parts of the project flow. Here `getPythonProjects` is used as an example function but behavior will mirror other getter and setter functions exposed in the API.
+
+1. **API Call:** Extensions can calls `getPythonProjects` on [`PythonEnvironmentApi`](../src/api.ts).
+2. **API Implementation:** [`PythonEnvironmentApiImpl`](../src/features/pythonApi.ts) delegates to its internal project manager.
+3. **Internal API:** The project manager is typed as [`PythonProjectManager`](../src/internal.api.ts).
+4. **Concrete Implementation:** [`PythonProjectManagerImpl`](../src/features/projectManager.ts) implements the actual logic.
+5. **Data Model:** Returns an array of [`PythonProject`](../src/api.ts) objects.
+
+## Project Creators
+This is how creating projects work with the API as it uses a method of registering
+external or internal project creators and maintaining project states internally in
+just this extension.
+
+- **Project Creators:** Any extension can implement and register a project creator by conforming to the [`PythonProjectCreator`](../src/api.ts) interface. Each creator provides a `create` method that returns one or more new projects (or their URIs). The create method is responsible for add the new projects to the project manager.
+- **Registration:** Project creators are registered with the API, making them discoverable and usable by the extension or other consumers.
+- **Integration:** Once a project is created, it is added to the internal project manager (`PythonProjectManagerImpl` in [`src/features/projectManager.ts`](../src/features/projectManager.ts)), which updates the set of known projects and persists settings if necessary.
+
+### What an Extension Must Do
+
+1. **Implement the Creator Interface:**
+   - Create a class that implements the [`PythonProjectCreator`](../src/api.ts) interface.
+   - Provide a unique `name`, a user-friendly `displayName`, and a `create` method that returns one or more `PythonProject` objects or URIs.
+
+2. **Register the Creator:**
+   - Register the creator with the main API (usually via a registration method exposed by this extension’s API surface).
+   - This makes the creator discoverable and usable by the extension and other consumers.
+
+3. **Add Projects Directly:**
+   - If your creator directly creates `PythonProject` objects, you MUST call the internal project manager’s `add` method during your create function to add projects as ones in the workspace.
+
+
+### Responsibilities Table
+
+| Step                                       | External Extension’s Responsibility | Internal Python-Envs-Ext Responsibility |
+| ------------------------------------------ | :---------------------------------: | :-------------------------------------: |
+| Implement `PythonProjectCreator` interface |                  ☑️                  |                                         |
+| Register the creator                       |                  ☑️                  |                                         |
+| Provide `create` method                    |                  ☑️                  |                                         |
+| Add projects to project manager            |                  ☑️                  |                                         |
+| Update project settings                    |                                     |                    ☑️                    |
+| Track and list creators                    |                                     |                    ☑️                    |
+| Invoke creator and handle results          |                                     |                    ☑️                    |
+
+
+### Example Implementation: [`ExistingProjects`](../src/features/creators/existingProjects.ts)
+
+The [`ExistingProjects`](../src/features/creators/existingProjects.ts) class is an example of a project creator. It allows users to select files or folders from the workspace and creates new `PythonProject` instances for them. After creation, these projects are added to the internal project manager:
+
+create function implementation abbreviated:
+```typescript
+async create(
+        _options?: PythonProjectCreatorOptions,
+    ): Promise<PythonProject | PythonProject[] | Uri | Uri[] | undefined> {
+const projects = resultsInWorkspace.map(
+                (uri) => new PythonProjectsImpl(path.basename(uri.fsPath), uri),
+            ) as PythonProject[];
+this.pm.add(projects);
+return projects;
+    }
+```
+
+creator registration (usually on extension activation):
+```
+  projectCreators.registerPythonProjectCreator(new ExistingProjects(projectManager)),
+
+```
+
+- **Implements:** [`PythonProjectCreator`](../src/api.ts)
+- **Adds projects to:** `PythonProjectManager` (see below)
+
+
+

src/features/projectManager.ts

@@ -24,6 +24,8 @@ export class PythonProjectManagerImpl implements PythonProjectManager {
     private _projects = new Map<string, PythonProject>();
     private readonly _onDidChangeProjects = new EventEmitter<ProjectArray | undefined>();
     public readonly onDidChangeProjects = this._onDidChangeProjects.event;
+
+    // Debounce the updateProjects method to avoid excessive update calls
     private readonly updateDebounce = createSimpleDebounce(100, () => this.updateProjects());
 
     initialize(): void {
@@ -46,17 +48,24 @@ export class PythonProjectManagerImpl implements PythonProjectManager {
         );
     }
 
+    /**
+     *
+     * Gathers the projects which are configured in settings and all workspace roots.
+     * @returns An array of PythonProject objects representing the initial projects.
+     */
     private getInitialProjects(): ProjectArray {
         const newProjects: ProjectArray = [];
         const workspaces = getWorkspaceFolders() ?? [];
         for (const w of workspaces) {
             const config = getConfiguration('python-envs', w.uri);
             const overrides = config.get<PythonProjectSettings[]>('pythonProjects', []);
 
+            // Add the workspace root as a project if not already present
             if (!newProjects.some((p) => p.uri.toString() === w.uri.toString())) {
                 newProjects.push(new PythonProjectsImpl(w.name, w.uri));
             }
 
+            // For each override, resolve its path and add as a project if not already present
             for (const o of overrides) {
                 const uri = Uri.file(path.resolve(w.uri.fsPath, o.path));
                 if (!newProjects.some((p) => p.uri.toString() === uri.toString())) {
@@ -67,31 +76,22 @@ export class PythonProjectManagerImpl implements PythonProjectManager {
         return newProjects;
     }
 
+    /**
+     * Get initial projects from the workspace(s) config settings
+     * then updates the internal _projects map to reflect the current state and
+     * fires the onDidChangeProjects event if there are any changes.
+     */
     private updateProjects(): void {
-        const workspaces = getWorkspaceFolders() ?? [];
+        const newProjects: ProjectArray = this.getInitialProjects();
         const existingProjects = Array.from(this._projects.values());
-        const newProjects: ProjectArray = [];
-
-        for (const w of workspaces) {
-            const config = getConfiguration('python-envs', w.uri);
-            const overrides = config.get<PythonProjectSettings[]>('pythonProjects', []);
-
-            if (!newProjects.some((p) => p.uri.toString() === w.uri.toString())) {
-                newProjects.push(new PythonProjectsImpl(w.name, w.uri));
-            }
-            for (const o of overrides) {
-                const uri = Uri.file(path.resolve(w.uri.fsPath, o.path));
-                if (!newProjects.some((p) => p.uri.toString() === uri.toString())) {
-                    newProjects.push(new PythonProjectsImpl(o.path, uri));
-                }
-            }
-        }
 
+        // Remove projects that are no longer in the workspace settings
         const projectsToRemove = existingProjects.filter(
             (w) => !newProjects.find((n) => n.uri.toString() === w.uri.toString()),
         );
         projectsToRemove.forEach((w) => this._projects.delete(w.uri.toString()));
 
+        // Add new projects that are in the workspace settings but not in the existing projects
         const projectsToAdd = newProjects.filter(
             (n) => !existingProjects.find((w) => w.uri.toString() === n.uri.toString()),
         );
@@ -136,6 +136,7 @@ export class PythonProjectManagerImpl implements PythonProjectManager {
                 // for non-root projects, always add setting
                 edits.push({ project: currProject, envManager: envManagerId, packageManager: pkgManagerId });
             }
+            // handles adding the project to this._projects map
             return this._projects.set(currProject.uri.toString(), currProject);
         });
         this._onDidChangeProjects.fire(Array.from(this._projects.values()));
@@ -156,6 +157,7 @@ export class PythonProjectManagerImpl implements PythonProjectManager {
     }
 
     getProjects(uris?: Uri[]): ReadonlyArray<PythonProject> {
+        console.log('getProjects', uris);
         if (uris === undefined) {
             return Array.from(this._projects.values());
         } else {
@@ -178,6 +180,11 @@ export class PythonProjectManagerImpl implements PythonProjectManager {
         return pythonProject;
     }
 
+    /**
+     * Finds the single project that matches the given URI if it exists.
+     * @param uri The URI of the project to find.
+     * @returns The project with the given URI, or undefined if not found.
+     */
     private findProjectByUri(uri: Uri): PythonProject | undefined {
         const _projects = Array.from(this._projects.values()).sort((a, b) => b.uri.fsPath.length - a.uri.fsPath.length);
 
@@ -191,6 +198,13 @@ export class PythonProjectManagerImpl implements PythonProjectManager {
         return undefined;
     }
 
+    /**
+     * Checks if a given file or folder path (normalizedUriPath)
+     * is the same as, or is inside, a project path
+     * @normalizedProjectPath Project path to check against.
+     * @normalizedUriPath File or folder path to check.
+     * @returns true if the file or folder path is the same as or inside the project path, false otherwise.
+     */
     private isUriMatching(normalizedUriPath: string, normalizedProjectPath: string): boolean {
         if (normalizedProjectPath === normalizedUriPath) {
             return true;