Removed comments, made Settings members public, doc

src/settings/mod.rs

@@ -6,7 +6,6 @@ use serde::{Deserialize, Serialize};
 extern crate log;
 use log::{error, info};
 
-// mod utils;
 pub mod utils;
 use utils::SettingsType;
 
@@ -89,19 +88,45 @@ macro_rules! decode_settings {
     };
 }
 
-#[derive(Debug, Deserialize, Serialize)]
+/// Representation of the software’s settings
+///
+/// This struct represents all the settings the software has to follow
+/// while running, which includes the phoneme categories as well as
+/// the soundchange rules to apply to the input text.
+#[derive(Clone, Debug, Deserialize, Serialize)]
 pub struct Settings {
+    /// Represents the version of the loaded ruleset.
+    ///
+    /// It is used to detect obsolete ruleset representations or if a
+    /// loaded ruleset comes from a newer version of lang_evolve_core
+    /// than the one used by the user.
     #[serde(default = "Settings::get_ruleset_version")]
-    version: String,
+    pub version: String,
+
+    /// Categories of phonemes
+    ///
+    /// This is a vector of categories of phonemes, represented
+    /// themselves as pairs of strings. Each pair of strings has its
+    /// first element represent the name of the category, which is
+    /// generally represented by a single capital letter. The second
+    /// element is a string where all its characters represent
+    /// phonemes. It is currently not possible to have more than one
+    /// character to be considered as one sound.
     #[serde(default)]
-    categories: Vec<(String, String)>,
+    pub categories: Vec<(String, String)>,
+
+    /// Soundchange rules
+    ///
+    /// This is a vector of pairs of strings, the first one represents
+    /// a regex to be matched while the second represents the change
+    /// to be made to the input data.
     #[serde(default)]
     rules: Vec<(String, String)>,
 }
 
 /// Representation inside the crate of LangEvolve’s settings.
 impl Settings {
-    /// Creates a new empty instance of `Settings`
+    /// Creates a new empty instance of [`Settings`]
     ///
     /// # Example
     ///
@@ -115,6 +140,8 @@ impl Settings {
     /// assert_eq!(content_yaml, serde_yaml::to_string(&s).unwrap());
     /// assert_eq!(content_json, serde_json::to_string(&s).unwrap());
     /// ```
+    ///
+    /// [`Settings`]: ./settings/struct.Settings.html
     pub fn new() -> Self {
         Self {
             version: Self::get_ruleset_version(),
@@ -123,12 +150,11 @@ impl Settings {
         }
     }
 
-    /// Import settings from an imput file. The currently allowed file formats
-    /// are:
-    /// - JSON - with the `.json` extension
-    /// - Yaml - with the `.yaml` or `.yml` extension
-    /// The format will be automatically detected based on the filename
-    /// extension.
+    /// Import settings from an imput file.
+    ///
+    /// The currently allowed file formats are described in the
+    /// [`utils::SettingsType`] enum. If the ruleset version is higher than the
+    /// current version (see [`Settings.version`]), then an error is returned.
     ///
     /// # Arguments
     ///
@@ -148,6 +174,9 @@ impl Settings {
     /// let path_yml = Path::new("settings.yml");
     /// let _s_yml = Settings::import(&path_yml).unwrap();
     /// ```
+    ///
+    /// [`utils::SettingsTYpe`]: ./utils/enum.SettingsType.html
+    /// [`Settings.version`]: ./struct.Settings.html#structfield.version
     pub fn import(path: &std::path::Path) -> std::io::Result<Self> {
         use utils::SettingsType::{Json, Yaml};
         let file_type = utils::get_file_type(&path);
@@ -172,16 +201,40 @@ impl Settings {
                 }
             },
         };
+        if settings.version > Self::get_ruleset_version() {
+            error!("Ruleset version too high!");
+            return Err(std::io::Error::new(
+                std::io::ErrorKind::InvalidData,
+                "Ruleset version too high!",
+            ));
+        }
         info!("Successfuly imported {}", path.display());
         Ok(settings)
     }
 
-    /// Export the current rules to a file. The allowed file formats are either
-    /// a YAML file or a Json file, hence the allowed filename extension are:
-    /// * "yml" or "yaml" for Yaml files
-    /// * "json" for Json files
-    /// The format is detected automatically depending on the extension of the
-    /// filename.
+    /// Import settings from file path described by the argument `path`
+    ///
+    /// # Arguments
+    ///
+    /// * `path` - path to the file from which settings should be imported
+    ///
+    /// # Example
+    ///
+    /// ```no_run
+    /// let s = lang_evolve_core::settings::Settings::from("settings.yml");
+    /// ```
+    pub fn from<S>(s: S) -> Self
+    where
+        S: ToString,
+    {
+        let s = s.to_string();
+        let path = std::path::Path::new(&s);
+        Self::import(&path).unwrap()
+    }
+
+    /// Export current settings to a file.
+    ///
+    /// The allowed file formats are described in the [`SettingsType`] enum.
     ///
     /// # Arguments
     ///
@@ -203,6 +256,8 @@ impl Settings {
     /// let path_yml = Path::new("./output.yml");
     /// s.export(&path_yml).unwrap();
     /// ```
+    ///
+    /// [`SettingsType`]: ./utils/enum.SettingsType.html
     pub fn export(&self, path: &std::path::Path) -> std::io::Result<()> {
         let filetype = utils::get_file_type(&path);
         let content = match filetype {