From a67e63cce0443a2a289fdfc275a41cff704cd35e Mon Sep 17 00:00:00 2001
From: mo8it <mo8it@proton.me>
Date: Mon, 13 May 2024 22:02:45 +0200
Subject: [PATCH] Document info_file

---
 src/exercise.rs  |  3 +--
 src/info_file.rs | 43 ++++++++++++++++++++++++++++++++++---------
 2 files changed, 35 insertions(+), 11 deletions(-)

diff --git a/src/exercise.rs b/src/exercise.rs
index a63c9aac..4bc37cd7 100644
--- a/src/exercise.rs
+++ b/src/exercise.rs
@@ -17,10 +17,9 @@ use crate::{
 /// The initial capacity of the output buffer.
 pub const OUTPUT_CAPACITY: usize = 1 << 14;
 
+/// See `info_file::ExerciseInfo`
 pub struct Exercise {
-    /// Directory name.
     pub dir: Option<&'static str>,
-    /// Exercise's unique name.
     pub name: &'static str,
     /// Path of the exercise file starting with the `exercises/` directory.
     pub path: &'static str,
diff --git a/src/info_file.rs b/src/info_file.rs
index 14b886b2..0c459284 100644
--- a/src/info_file.rs
+++ b/src/info_file.rs
@@ -4,44 +4,69 @@ use std::{fs, io::ErrorKind};
 
 use crate::embedded::EMBEDDED_FILES;
 
-// Deserialized from the `info.toml` file.
+/// Deserialized from the `info.toml` file.
 #[derive(Deserialize)]
 pub struct ExerciseInfo {
-    // Name of the exercise
+    /// Exercise's unique name.
     pub name: String,
-    // The exercise's directory inside the `exercises` directory
+    /// Exercise's directory name inside the `exercises/` directory.
     pub dir: Option<String>,
     #[serde(default = "default_true")]
+    /// Run `cargo test` on the exercise.
     pub test: bool,
+    /// Deny all Clippy warnings.
     #[serde(default)]
     pub strict_clippy: bool,
-    // The hint text associated with the exercise
+    /// The exercise's hint to be shown to the user on request.
     pub hint: String,
 }
-#[inline]
+#[inline(always)]
 const fn default_true() -> bool {
     true
 }
 
 impl ExerciseInfo {
+    /// Path to the exercise file starting with the `exercises/` directory.
     pub fn path(&self) -> String {
-        if let Some(dir) = &self.dir {
-            format!("exercises/{dir}/{}.rs", self.name)
+        let mut path = if let Some(dir) = &self.dir {
+            // 14 = 10 + 1 + 3
+            // exercises/ + / + .rs
+            let mut path = String::with_capacity(14 + dir.len() + self.name.len());
+            path.push_str("exercises/");
+            path.push_str(dir);
+            path.push('/');
+            path
         } else {
-            format!("exercises/{}.rs", self.name)
-        }
+            // 13 = 10 + 3
+            // exercises/ + .rs
+            let mut path = String::with_capacity(13 + self.name.len());
+            path.push_str("exercises/");
+            path
+        };
+
+        path.push_str(&self.name);
+        path.push_str(".rs");
+
+        path
     }
 }
 
+/// The deserialized `info.toml` file.
 #[derive(Deserialize)]
 pub struct InfoFile {
+    /// For possible breaking changes in the future for third-party exercises.
     pub format_version: u8,
+    /// Shown to users when starting with the exercises.
     pub welcome_message: Option<String>,
+    /// Shown to users after finishing all exercises.
     pub final_message: Option<String>,
+    /// List of all exercises.
     pub exercises: Vec<ExerciseInfo>,
 }
 
 impl InfoFile {
+    /// Official exercises: Parse the embedded `info.toml` file.
+    /// Third-party exercises: Parse the `info.toml` file in the current directory.
     pub fn parse() -> Result<Self> {
         // Read a local `info.toml` if it exists.
         let slf = match fs::read_to_string("info.toml") {