minor edits

Author: eleanorjboyd

src/features/creators/creationHelpers.ts

@@ -6,8 +6,8 @@ import { CreateEnvironmentOptions, EnvironmentManager } from '../../api';
 import { traceVerbose } from '../../common/logging';
 
 /**
- * Prompts the user to choose whether to create a new venv for a package.
- * Returns true if the user selects 'Yes', false if 'No', and undefined if cancelled.
+ * Prompts the user to choose whether to create a new virtual environment (venv) for a package.
+ * @returns {Promise<boolean | undefined>} Resolves to true if 'Yes' is selected, false if 'No', or undefined if cancelled.
  */
 export async function promptForVenv(): Promise<boolean | undefined> {
     const venvChoice = await window.showQuickPick(['Yes', 'No'], {
@@ -21,15 +21,16 @@ export async function promptForVenv(): Promise<boolean | undefined> {
 }
 
 /**
- * Returns true if GitHub Copilot extension is installed, false otherwise.
+ * Checks if the GitHub Copilot extension is installed in the current VS Code environment.
+ * @returns {boolean} True if Copilot is installed, false otherwise.
  */
 export function isCopilotInstalled(): boolean {
     return !!extensions.getExtension('GitHub.copilot');
 }
 
 /**
  * Prompts the user to choose whether to create a Copilot instructions file, only if Copilot is installed.
- * Returns true if the user selects 'Yes', false if 'No', and undefined if cancelled or Copilot not installed.
+ * @returns {Promise<boolean | undefined>} Resolves to true if 'Yes' is selected, false if 'No', or undefined if cancelled or Copilot is not installed.
  */
 export async function promptForCopilotInstructions(): Promise<boolean | undefined> {
     if (!isCopilotInstalled()) {
@@ -45,13 +46,25 @@ export async function promptForCopilotInstructions(): Promise<boolean | undefine
     return copilotChoice === 'Yes';
 }
 
+/**
+ * Removes the .github Copilot instructions folder from the specified destination folder, if it exists.
+ * @param destFolder - The absolute path to the destination folder where the .github folder may exist.
+ * @returns {Promise<void>} Resolves when the folder is removed or if it does not exist.
+ */
 export async function removeCopilotInstructions(destFolder: string) {
     const copilotFolder = path.join(destFolder, '.github');
     if (await fs.pathExists(copilotFolder)) {
         await fs.remove(copilotFolder);
     }
 }
 
+/**
+ * Quickly creates a new Python virtual environment (venv) in the specified destination folder using the available environment managers.
+ * Attempts to use the venv manager if available, otherwise falls back to any manager that supports environment creation.
+ * @param envManagers - The collection of available environment managers.
+ * @param destFolder - The absolute path to the destination folder where the environment should be created.
+ * @returns {Promise<void>} Resolves when the environment is created or an error is shown.
+ */
 export async function quickCreateNewVenv(envManagers: EnvironmentManagers, destFolder: string) {
     try {
         // get the environment manager for venv
@@ -86,10 +99,11 @@ export async function quickCreateNewVenv(envManagers: EnvironmentManagers, destF
 }
 
 /**
- * Replaces all occurrences of a string in a single file's contents, handling special regex characters in the search value.
- * @param filePath The path to the file to update.
- * @param searchValue The string to search for (will be escaped for regex).
- * @param replaceValue The string to replace with.
+ * Replaces all occurrences of a string in a single file's contents, safely handling special regex characters in the search value.
+ * @param filePath - The absolute path to the file to update.
+ * @param searchValue - The string to search for (will be escaped for regex).
+ * @param replaceValue - The string to replace with.
+ * @returns {Promise<void>} Resolves when the file has been updated.
  */
 export async function replaceInFile(filePath: string, searchValue: string, replaceValue: string) {
     // Escape special regex characters in searchValue
@@ -102,7 +116,13 @@ export async function replaceInFile(filePath: string, searchValue: string, repla
     }
 }
 
-// Helper to recursively replace all occurrences of a string in file/folder names and file contents
+/**
+ * Recursively replaces all occurrences of a string in file and folder names, as well as file contents, within a directory tree.
+ * @param dir - The root directory to start the replacement from.
+ * @param searchValue - The string to search for in names and contents.
+ * @param replaceValue - The string to replace with.
+ * @returns {Promise<void>} Resolves when all replacements are complete.
+ */
 export async function replaceInFilesAndNames(dir: string, searchValue: string, replaceValue: string) {
     const entries = await fs.readdir(dir, { withFileTypes: true });
     for (const entry of entries) {

src/features/creators/newPackageProject.ts

@@ -71,7 +71,7 @@ export class NewPackageProject implements PythonProjectCreator {
             window.showErrorMessage('No workspace folder is open.');
             return undefined;
         }
-        const destRoot = workspaceFolders[0].uri.fsPath;
+        const destRoot = workspaceFolders[0].uri.fsPath; // this doesn't seem right...
         const destFolder = path.join(destRoot, `${packageName}_project`);
         await fs.copy(templateFolder, destFolder);
 
@@ -88,19 +88,20 @@ export class NewPackageProject implements PythonProjectCreator {
             await quickCreateNewVenv(this.envManagers, destFolder);
         }
 
-        // 5. Replace <run_exec> and <activation_command> in README.md
-        const readmeFilePath = path.join(destFolder, 'README.md');
+        // 5. Get the Python environment for the destination folder
+        // could be either the one created in step 4 or an existing one
         const pythonEnvironment = await this.envManagers.getEnvironment(Uri.parse(destFolder));
+
+        // 6. Replace <run_exec> and <activation_command> in README.md
+        const readmeFilePath = path.join(destFolder, 'README.md');
         if (!pythonEnvironment) {
             window.showErrorMessage('Python environment not found.');
             return undefined;
         }
         const execInfo = pythonEnvironment.execInfo;
         if (execInfo.run) {
-            let execRunStr = execInfo.run.executable;
-            if (execInfo.run.args) {
-                execRunStr += ` ${execInfo.run.args.join(' ')}`;
-            }
+            const { executable, args = [] } = execInfo.run;
+            const execRunStr = [executable, ...args].join(' ');
             await replaceInFile(readmeFilePath, '<run_exec>', execRunStr);
         }
         // TODO: replace <activation_command> in README.md ?