Use public comments for public items

src/app_state.rs

@@ -330,8 +330,8 @@ impl AppState {
         }
     }
 
-    // Official exercises: Dump the solution file form the binary and return its path.
+    /// Official exercises: Dump the solution file form the binary and return its path.
-    // Third-party exercises: Check if a solution file exists and return its path in that case.
+    /// Third-party exercises: Check if a solution file exists and return its path in that case.
     pub fn current_solution_path(&self) -> Result<Option<String>> {
         if DEBUG_PROFILE {
             return Ok(None);
@@ -358,9 +358,9 @@ impl AppState {
         }
     }
 
-    // Mark the current exercise as done and move on to the next pending exercise if one exists.
+    /// Mark the current exercise as done and move on to the next pending exercise if one exists.
-    // If all exercises are marked as done, run all of them to make sure that they are actually
+    /// If all exercises are marked as done, run all of them to make sure that they are actually
-    // done. If an exercise which is marked as done fails, mark it as pending and continue on it.
+    /// done. If an exercise which is marked as done fails, mark it as pending and continue on it.
     pub fn done_current_exercise(&mut self, writer: &mut StdoutLock) -> Result<ExercisesProgress> {
         let exercise = &mut self.exercises[self.current_exercise_ind];
         if !exercise.done {

src/cargo_toml.rs

@@ -2,10 +2,10 @@ use anyhow::{Context, Result};
 
 use crate::info_file::ExerciseInfo;
 
-// Return the start and end index of the content of the list `bin = […]`.
+/// Return the start and end index of the content of the list `bin = […]`.
-// bin = [xxxxxxxxxxxxxxxxx]
+/// bin = [xxxxxxxxxxxxxxxxx]
-//        |start_ind       |
+///        |start_ind       |
-//                         |end_ind
+///                         |end_ind
 pub fn bins_start_end_ind(cargo_toml: &str) -> Result<(usize, usize)> {
     let start_ind = cargo_toml
         .find("bin = [")
@@ -20,8 +20,8 @@ pub fn bins_start_end_ind(cargo_toml: &str) -> Result<(usize, usize)> {
     Ok((start_ind, end_ind))
 }
 
-// Generate and append the content of the `bin` list in `Cargo.toml`.
+/// Generate and append the content of the `bin` list in `Cargo.toml`.
-// The `exercise_path_prefix` is the prefix of the `path` field of every list entry.
+/// The `exercise_path_prefix` is the prefix of the `path` field of every list entry.
 pub fn append_bins(
     buf: &mut Vec<u8>,
     exercise_infos: &[ExerciseInfo],
@@ -43,7 +43,7 @@ pub fn append_bins(
     }
 }
 
-// Update the `bin` list and leave everything else unchanged.
+/// Update the `bin` list and leave everything else unchanged.
 pub fn updated_cargo_toml(
     exercise_infos: &[ExerciseInfo],
     current_cargo_toml: &str,

src/cmd.rs

@@ -1,8 +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.
+/// 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.
+/// 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}``"))?;
@@ -37,18 +37,18 @@ pub struct CargoCmd<'a> {
     pub args: &'a [&'a str],
     pub exercise_name: &'a str,
     pub description: &'a str,
-    // RUSTFLAGS="-A warnings"
+    /// RUSTFLAGS="-A warnings"
     pub hide_warnings: bool,
-    // Added as `--target-dir` if `Self::dev` is true.
+    /// Added as `--target-dir` if `Self::dev` is true.
     pub target_dir: &'a Path,
-    // The output buffer to append the merged stdout and stderr.
+    /// The output buffer to append the merged stdout and stderr.
     pub output: &'a mut Vec<u8>,
-    // true while developing Rustlings.
+    /// true while developing Rustlings.
     pub dev: bool,
 }
 
 impl<'a> CargoCmd<'a> {
-    // Run `cargo SUBCOMMAND --bin EXERCISE_NAME … ARGS`.
+    /// Run `cargo SUBCOMMAND --bin EXERCISE_NAME … ARGS`.
     pub fn run(&mut self) -> Result<bool> {
         let mut cmd = Command::new("cargo");
         cmd.arg(self.subcommand);

src/embedded.rs

@@ -6,7 +6,7 @@ use std::{
 
 use crate::info_file::ExerciseInfo;
 
-// Contains all embedded files.
+/// Contains all embedded files.
 pub static EMBEDDED_FILES: EmbeddedFiles = rustlings_macros::include_files!();
 
 #[derive(Clone, Copy)]
@@ -73,16 +73,16 @@ impl ExerciseDir {
     }
 }
 
-// All embedded files.
+/// All embedded files.
 pub struct EmbeddedFiles {
-    // `info.toml`
+    /// The content of the `info.toml` file.
     pub info_file: &'static str,
     exercise_files: &'static [ExerciseFiles],
     exercise_dirs: &'static [ExerciseDir],
 }
 
 impl EmbeddedFiles {
-    // Dump all the embedded files of the `exercises/` direcotry.
+    /// Dump all the embedded files of the `exercises/` direcotry.
     pub fn init_exercises_dir(&self, exercise_infos: &[ExerciseInfo]) -> Result<()> {
         create_dir("exercises").context("Failed to create the directory `exercises`")?;
 
@@ -110,7 +110,7 @@ impl EmbeddedFiles {
         WriteStrategy::Overwrite.write(path, exercise_files.exercise)
     }
 
-    // Write the solution file to disk and return its path.
+    /// Write the solution file to disk and return its path.
     pub fn write_solution_to_disk(
         &self,
         exercise_ind: usize,

src/exercise.rs

@@ -14,7 +14,7 @@ use crate::{
     DEBUG_PROFILE,
 };
 
-// The initial capacity of the output buffer.
+/// The initial capacity of the output buffer.
 pub const OUTPUT_CAPACITY: usize = 1 << 14;
 
 pub struct Exercise {