From 32415e1e6cca9e0fb9a3019ed8e75956c7f7f92e Mon Sep 17 00:00:00 2001
From: mo8it <mo8it@proton.me>
Date: Wed, 1 May 2024 17:55:49 +0200
Subject: [PATCH] Document cmd

---
 src/cmd.rs | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/src/cmd.rs b/src/cmd.rs
index 28f21c55..e4bc1121 100644
--- a/src/cmd.rs
+++ b/src/cmd.rs
@@ -1,6 +1,8 @@
 use anyhow::{Context, Result};
 use std::{io::Read, path::Path, process::Command};
 
+// Run a command with a description for a possible error and append the merged stdout and stderr.
+// The boolean in the returned `Result` is true if the command's exit status is success.
 pub fn run_cmd(mut cmd: Command, description: &str, output: &mut Vec<u8>) -> Result<bool> {
     let (mut reader, writer) = os_pipe::pipe()
         .with_context(|| format!("Failed to create a pipe to run the command `{description}``"))?;
@@ -35,13 +37,18 @@ pub struct CargoCmd<'a> {
     pub args: &'a [&'a str],
     pub exercise_name: &'a str,
     pub description: &'a str,
+    // RUSTFLAGS="-A warnings"
     pub hide_warnings: bool,
+    // Added as `--target-dir` if `Self::dev` is true.
     pub target_dir: &'a Path,
+    // The output buffer to append the merged stdout and stderr.
     pub output: &'a mut Vec<u8>,
+    // true while developing Rustlings.
     pub dev: bool,
 }
 
 impl<'a> CargoCmd<'a> {
+    // Run `cargo SUBCOMMAND --bin EXERCISE_NAME … ARGS`.
     pub fn run(&mut self) -> Result<bool> {
         let mut cmd = Command::new("cargo");
         cmd.arg(self.subcommand);