Merge pull request #1058 from EnergySystemsModellingLab/code_documentation_fixes

Fixes for in-code documentation

Author: tsmbland

src/agent.rs

@@ -21,7 +21,7 @@ pub type AgentCommodityPortionsMap = HashMap<(CommodityID, u32), Dimensionless>;
 /// A map for the agent's search space, keyed by commodity and year
 pub type AgentSearchSpaceMap = HashMap<(CommodityID, u32), Rc<Vec<Rc<Process>>>>;
 
-/// A map of objectives for an agent, keyed by commodity and year.
+/// A map of objectives for an agent, keyed by year.
 ///
 /// NB: As we currently only support the "single" decision rule, the only parameter we need for
 /// objectives is the type.

src/asset.rs

@@ -63,7 +63,7 @@ pub struct AssetGroupID(u32);
 /// determined by the investment algorithm.
 ///
 /// `Future` and `Candidate` assets can be converted to `Commissioned` assets by calling
-/// `commission_future` or `commission_candidate` respectively.
+/// the `commission` method (or via pool operations that commission future/selected assets).
 ///
 /// `Commissioned` assets can be decommissioned by calling `decommission`.
 #[derive(Clone, Debug, PartialEq, strum::Display)]
@@ -826,12 +826,12 @@ impl Asset {
             mothballed_year, ..
         } = &self.state
         else {
-            panic!("Cannot mothball an asset that hasn't been commissioned")
+            panic!("Cannot get mothballed year for an asset that hasn't been commissioned")
         };
         *mothballed_year
     }
 
-    /// Checks if the assets corresponds to a process that has a `unit_size` and is therefore divisible.
+    /// Checks if the asset corresponds to a process that has a `unit_size` and is therefore divisible.
     pub fn is_divisible(&self) -> bool {
         self.process.unit_size.is_some()
     }

src/cli.rs

@@ -1,4 +1,4 @@
-//! The command line interface for the simulation.
+//! Command-line interface for the MUSE2 simulation.
 use crate::graph::save_commodity_graphs_for_model;
 use crate::input::{load_commodity_graphs, load_model};
 use crate::log;
@@ -105,7 +105,7 @@ impl Commands {
     }
 }
 
-/// Parse CLI arguments and start MUSE2
+/// Parse CLI arguments and run the requested command or show help.
 pub fn run_cli() -> Result<()> {
     let cli = Cli::parse();
 

src/graph.rs

@@ -69,12 +69,11 @@ impl Display for GraphEdge {
 
 /// Helper function to return a possible flow operating in the requested year
 ///
-/// We are interested only on the flows direction, which are always the same for all years. So this
-/// function checks if the process can be operating in the target year and region and, if so, it
-/// returns its flows. It considers not only when the process can be commissioned, but also the
-/// lifetime of the process, since a process can be opperating many years after the commission time
-/// window is over. If the process cannot be opperating in the target year and region, None is
-/// returned.
+/// We are only interested in the flow directions, which are constant across years. This
+/// function checks whether the process can be operating in the target region and year and, if so,
+/// returns its flows. It considers both the commission year and the process lifetime, since a
+/// process may operate for years after its commission window. If the process cannot be operating
+/// in the target region/year, `None` is returned.
 fn get_flow_for_year(
     process: &Process,
     target: (RegionID, u32),
@@ -85,7 +84,7 @@ fn get_flow_for_year(
     }
 
     // Otherwise we try to find one that operates in the target year. It is assumed that
-    // parameters are defined in the same (region, year) combinations than flows, at least.
+    // parameters are defined for at least the same (region, year) combinations as flows.
     let (target_region, target_year) = target;
     for ((region, year), value) in &process.flows {
         if *region != target_region {

src/graph/validate.rs

@@ -100,7 +100,7 @@ fn can_be_active(
 
 /// Validates that the commodity graph follows the rules for different commodity types.
 ///
-/// It takes as input a graph created by `create_commodities_graph_for_validation`, which is built
+/// It takes as input a graph prepared by `prepare_commodities_graph_for_validation`, which is built
 /// for a specific time slice selection (must match the `time_slice_level` passed to this function).
 ///
 /// The validation is only performed for commodities with the specified time slice level. For full

src/id.rs

@@ -103,15 +103,15 @@ pub(crate) use define_id_getter;
 
 /// A data structure containing a set of IDs
 pub trait IDCollection<ID: IDLike> {
-    /// Check if the ID is in the collection, returning a copy of it if found.
+    /// Check if the ID is in the collection, returning a reference to it if found.
     ///
     /// # Arguments
     ///
     /// * `id` - The ID to check (can be string or ID type)
     ///
     /// # Returns
     ///
-    /// A copy of the ID in `self`, or an error if not found.
+    /// A reference to the ID in `self`, or an error if not found.
     fn get_id<T: Borrow<str> + Display + ?Sized>(&self, id: &T) -> Result<&ID>;
 }
 

src/input.rs

@@ -51,7 +51,7 @@ impl<K: Eq + Hash, V> Insert<K, V> for IndexMap<K, V> {
 
 /// Read a series of type `T`s from a CSV file.
 ///
-/// Will raise an error if the file is empty.
+/// Returns an error if the file is empty.
 ///
 /// # Arguments
 ///
@@ -178,9 +178,11 @@ where
     iter.into_iter().tuple_windows().all(|(a, b)| a < b)
 }
 
-/// Inserts a key-value pair into a `HashMap` if the key does not already exist.
+/// Insert a key-value pair into a map implementing the `Insert` trait if the key does not
+/// already exist.
 ///
-/// If the key already exists, it returns an error with a message indicating the key's existence.
+/// If the key already exists, this returns an error with a message indicating the key's
+/// existence.
 pub fn try_insert<M, K, V>(map: &mut M, key: &K, value: V) -> Result<()>
 where
     M: Insert<K, V>,

src/input/agent.rs

@@ -42,12 +42,13 @@ struct AgentRaw {
 ///
 /// * `model_dir` - Folder containing model configuration files
 /// * `commodities` - Commodities for the model
-/// * `process_ids` - The possible valid process IDs
+/// * `processes` - Processes available in the model
 /// * `region_ids` - The possible valid region IDs
+/// * `milestone_years` - Milestone years in the model
 ///
 /// # Returns
 ///
-/// A map of Agents, with the agent ID as the key
+/// A map of agents keyed by agent ID
 pub fn read_agents(
     model_dir: &Path,
     commodities: &CommodityMap,
@@ -89,17 +90,16 @@ pub fn read_agents(
     Ok(agents)
 }
 
-/// Read agents info from the agents.csv file.
+/// Read agents info from the `agents.csv` file.
 ///
 /// # Arguments
 ///
 /// * `model_dir` - Folder containing model configuration files
-/// * `commodities` - Commodities for the model
-/// * `process_ids` - The possible valid process IDs
+/// * `region_ids` - The possible valid region IDs
 ///
 /// # Returns
 ///
-/// A map of Agents, with the agent ID as the key
+/// A map of agents keyed by agent ID
 fn read_agents_file(model_dir: &Path, region_ids: &IndexSet<RegionID>) -> Result<AgentMap> {
     let file_path = model_dir.join(AGENT_FILE_NAME);
     let agents_csv = read_csv(&file_path)?;

src/input/agent/commodity_portion.rs

@@ -1,4 +1,4 @@
-//! Code for reading the agent commodities CSV file.
+//! Code for reading agent commodity portions from a CSV file.
 use super::super::{deserialise_proportion_nonzero, input_err_msg, read_csv, try_insert};
 use crate::agent::{AgentCommodityPortionsMap, AgentID, AgentMap};
 use crate::commodity::{CommodityMap, CommodityType};
@@ -33,10 +33,14 @@ struct AgentCommodityPortionRaw {
 /// # Arguments
 ///
 /// * `model_dir` - Folder containing model configuration files
+/// * `agents` - Known agents in the model
+/// * `commodities` - Known commodities in the model
+/// * `region_ids` - Known region identifiers
+/// * `milestone_years` - Milestone years used by the model
 ///
 /// # Returns
 ///
-/// A map of Agents, with the agent ID as the key
+/// A `HashMap` mapping `AgentID` to `AgentCommodityPortionsMap`.
 pub fn read_agent_commodity_portions(
     model_dir: &Path,
     agents: &AgentMap,

src/input/agent/objective.rs

@@ -1,4 +1,4 @@
-//! Code for reading the agent objectives CSV file.
+//! Code for reading agent objectives from a CSV file.
 use super::super::{input_err_msg, read_csv, try_insert};
 use crate::ISSUES_URL;
 use crate::agent::{AgentID, AgentMap, AgentObjectiveMap, DecisionRule, ObjectiveType};
@@ -17,11 +17,11 @@ const AGENT_OBJECTIVES_FILE_NAME: &str = "agent_objectives.csv";
 /// An objective for an agent with associated parameters
 #[derive(Debug, Clone, Deserialize, PartialEq)]
 struct AgentObjectiveRaw {
-    /// Unique agent id identifying the agent this objective belongs to
+    /// Unique agent id identifying the agent this objective belongs to.
     agent_id: AgentID,
     /// The year(s) the objective is relevant for
     years: String,
-    /// Acronym identifying the objective (e.g. LCOX)
+    /// Acronym identifying the objective (e.g. LCOX).
     objective_type: ObjectiveType,
     /// For the weighted sum decision rule, the set of weights to apply to each objective.
     decision_weight: Option<Dimensionless>,
@@ -39,7 +39,7 @@ struct AgentObjectiveRaw {
 ///
 /// # Returns
 ///
-/// A map of Agents, with the agent ID as the key
+/// A `HashMap` mapping `AgentID` to `AgentObjectiveMap`.
 pub fn read_agent_objectives(
     model_dir: &Path,
     agents: &AgentMap,