feat: add comments

dist/main/index.js

@@ -27542,16 +27542,25 @@ var __webpack_exports__ = {};
 const core = __nccwpck_require__(4708);
 
 async function main() {
+    // Find the current time since the UNIX epoch.
     const stamp = Date.now();
-    core.info(`Creating timestamp at ${new Date(stamp)}. All files in the \`target\` folder not accessed between now and the end of the run will be purged.`);
+
+    core.info(`Creating timestamp at ${new Date(stamp)}.`);
+    core.info("All files in the `target` folder not accessed between now and the end of the run will be purged.")
+
+    // Save the timestamp so that it can be accessed in the post step.
     core.saveState("timestamp", stamp);
 }
 
 try {
     main();
+
     core.saveState("failed", "false");
 } catch (err) {
     core.setFailed(`Action failed with error: ${err}`);
+
+    // The post action will, by default, always run. This signals that an error occurred and it
+    // should not proceed.
     core.saveState("failed", "true");
 }
 

dist/post/index.js

@@ -27555,9 +27555,14 @@ const path = __nccwpck_require__(6928);
 const stream = __nccwpck_require__(2203);
 
 /**
+ * Returns the path to the `target` directory of the current Cargo project.
+ *
  * @returns {string}
  */
 async function locateTarget() {
+    // An array of strings, where each string is a line outputted by `cargo locate-project`. Note
+    // that `exec.exec()` doesn't guarantee that each written string will be a line (separated by
+    // `\n`), so this should be considered a hack and may break in the future.
     const lines = [];
 
     const outStream = new stream.Writable({
@@ -27567,35 +27572,42 @@ async function locateTarget() {
         }
     });
 
+    // Locate the absolute path to `Cargo.toml`.
     await exec.exec(
         "cargo locate-project",
         ["--workspace", "--message-format=plain", "--color=never"],
         { outStream },
     );
 
+    // Destroy the stream, just in case it wasn't done so already.
     outStream.destroy();
 
+    // From the path to `Cargo.toml`, return the path to `target`.
     return path.join(lines[1], "../", "target");
 }
 
 async function main() {
     const stamp = core.getState("timestamp");
-    core.info(`Using timestamp: ${stamp}.`);
+    core.info(`Using timestamp: ${new Date(stamp)}.`);
 
     // Remove everything older than timestamp.
     core.info("Sweeping unused files.");
 
     // Find `target` folder.
     const targetPath = await locateTarget();
 
+    // Iterate recursively over all files in `target`.
     for (const file of await fs.readdir(targetPath, { recursive: true })) {
         const filePath = path.join(targetPath, file);
         const stat = await fs.stat(filePath);
 
-        if (!stat.isFile()) {
+        // Skip over folders, since they cannot be deleted with `fs.rm()` and take up a minimal
+        // amount of space.
+        if (stat.isDirectory()) {
             continue;
         }
 
+        // If the file's last access time is older than the timestamp, delete it.
         if (stat.atime.getTime() < stamp) {
             core.info(`Deleting ${filePath}.`);
             await fs.rm(filePath);

src/main.js

@@ -1,15 +1,24 @@
 const core = require("@actions/core");
 
 async function main() {
+    // Find the current time since the UNIX epoch.
     const stamp = Date.now();
-    core.info(`Creating timestamp at ${new Date(stamp)}. All files in the \`target\` folder not accessed between now and the end of the run will be purged.`);
+
+    core.info(`Creating timestamp at ${new Date(stamp)}.`);
+    core.info("All files in the `target` folder not accessed between now and the end of the run will be purged.")
+
+    // Save the timestamp so that it can be accessed in the post step.
     core.saveState("timestamp", stamp);
 }
 
 try {
     main();
+
     core.saveState("failed", "false");
 } catch (err) {
     core.setFailed(`Action failed with error: ${err}`);
+
+    // The post action will, by default, always run. This signals that an error occurred and it
+    // should not proceed.
     core.saveState("failed", "true");
 }

src/post.js

@@ -6,9 +6,14 @@ const path = require("path");
 const stream = require("stream");
 
 /**
+ * Returns the path to the `target` directory of the current Cargo project.
+ *
  * @returns {string}
  */
 async function locateTarget() {
+    // An array of strings, where each string is a line outputted by `cargo locate-project`. Note
+    // that `exec.exec()` doesn't guarantee that each written string will be a line (separated by
+    // `\n`), so this should be considered a hack and may break in the future.
     const lines = [];
 
     const outStream = new stream.Writable({
@@ -18,35 +23,42 @@ async function locateTarget() {
         }
     });
 
+    // Locate the absolute path to `Cargo.toml`.
     await exec.exec(
         "cargo locate-project",
         ["--workspace", "--message-format=plain", "--color=never"],
         { outStream },
     );
 
+    // Destroy the stream, just in case it wasn't done so already.
     outStream.destroy();
 
+    // From the path to `Cargo.toml`, return the path to `target`.
     return path.join(lines[1], "../", "target");
 }
 
 async function main() {
     const stamp = core.getState("timestamp");
-    core.info(`Using timestamp: ${stamp}.`);
+    core.info(`Using timestamp: ${new Date(stamp)}.`);
 
     // Remove everything older than timestamp.
     core.info("Sweeping unused files.");
 
     // Find `target` folder.
     const targetPath = await locateTarget();
 
+    // Iterate recursively over all files in `target`.
     for (const file of await fs.readdir(targetPath, { recursive: true })) {
         const filePath = path.join(targetPath, file);
         const stat = await fs.stat(filePath);
 
-        if (!stat.isFile()) {
+        // Skip over folders, since they cannot be deleted with `fs.rm()` and take up a minimal
+        // amount of space.
+        if (stat.isDirectory()) {
             continue;
         }
 
+        // If the file's last access time is older than the timestamp, delete it.
         if (stat.atime.getTime() < stamp) {
             core.info(`Deleting ${filePath}.`);
             await fs.rm(filePath);