From f51357279d6ce933f70f7e014738d84407674614 Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Tue, 21 Feb 2017 13:00:20 +0100 Subject: [PATCH 1/3] Enhance documentation of configuration module --- libimagrt/src/configuration.rs | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/libimagrt/src/configuration.rs b/libimagrt/src/configuration.rs index 7f26490d..4601023e 100644 --- a/libimagrt/src/configuration.rs +++ b/libimagrt/src/configuration.rs @@ -36,9 +36,7 @@ generate_error_module!( pub use self::error::{ConfigError, ConfigErrorKind}; -/** - * Result type of this module. Either `T` or `ConfigError` - */ +/// Result type of this module. Either `T` or `ConfigError` pub type Result = RResult; /// `Configuration` object @@ -90,15 +88,18 @@ impl Configuration { }) } + /// Get the Editor setting from the configuration pub fn editor(&self) -> Option<&String> { self.editor.as_ref() } #[allow(dead_code)] // Why do I actually need this annotation on a pub function? + /// Get the underlying configuration TOML object pub fn config(&self) -> &Value { &self.config } + /// Get the configuration of the store, if any. pub fn store_config(&self) -> Option<&Value> { match self.config { Value::Table(ref tabl) => tabl.get("store"), @@ -208,11 +209,9 @@ fn get_editor_opts(v: &Value) -> String { } } -/** - * Helper to fetch the config file - * - * Tests several variants for the config file path and uses the first one which works. - */ +/// Helper to fetch the config file +/// +/// Tests several variants for the config file path and uses the first one which works. fn fetch_config(rtp: &PathBuf) -> Result { use std::env; use std::fs::File; From bc545f2b1e47a06e7205eb023a03591e9298cc8c Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Tue, 21 Feb 2017 15:26:10 +0100 Subject: [PATCH 2/3] Add some documentation to logger backend of runtime --- libimagrt/src/logger.rs | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/libimagrt/src/logger.rs b/libimagrt/src/logger.rs index d0efc82f..992a9d94 100644 --- a/libimagrt/src/logger.rs +++ b/libimagrt/src/logger.rs @@ -26,6 +26,7 @@ use ansi_term::Style; use ansi_term::Colour; use ansi_term::ANSIString; +/// Logger implementation for `log` crate. pub struct ImagLogger { prefix: String, dbg_fileline: bool, @@ -35,6 +36,7 @@ pub struct ImagLogger { impl ImagLogger { + /// Create a new ImagLogger object with a certain level pub fn new(lvl: LogLevel) -> ImagLogger { ImagLogger { prefix: "[imag]".to_owned(), @@ -44,21 +46,25 @@ impl ImagLogger { } } + /// Set debugging to include file and line pub fn with_dbg_file_and_line(mut self, b: bool) -> ImagLogger { self.dbg_fileline = b; self } + /// Set debugging to include prefix pub fn with_prefix(mut self, pref: String) -> ImagLogger { self.prefix = pref; self } + /// Set debugging to have color pub fn with_color(mut self, b: bool) -> ImagLogger { self.color_enabled = b; self } + /// Helper function to colorize a string with a certain Style fn style_or_not(&self, c: Style, s: String) -> ANSIString { if self.color_enabled { c.paint(s) @@ -67,6 +73,7 @@ impl ImagLogger { } } + /// Helper function to colorize a string with a certain Color fn color_or_not(&self, c: Colour, s: String) -> ANSIString { if self.color_enabled { c.paint(s) From d9569e6169f92c4aa21733b03833ff6d4c24f19a Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Tue, 21 Feb 2017 15:31:24 +0100 Subject: [PATCH 3/3] Add documentation for Runtime functions --- libimagrt/src/runtime.rs | 81 +++++++++++++++++++--------------------- 1 file changed, 39 insertions(+), 42 deletions(-) diff --git a/libimagrt/src/runtime.rs b/libimagrt/src/runtime.rs index b821e66d..07cd86c8 100644 --- a/libimagrt/src/runtime.rs +++ b/libimagrt/src/runtime.rs @@ -37,6 +37,9 @@ use logger::ImagLogger; use libimagstore::store::Store; +/// The Runtime object +/// +/// This object contains the complete runtime environment of the imag application running. #[derive(Debug)] pub struct Runtime<'a> { rtp: PathBuf, @@ -47,14 +50,11 @@ pub struct Runtime<'a> { impl<'a> Runtime<'a> { - /** - * Gets the CLI spec for the program and retreives the config file path (or uses the default on - * in $HOME/.imag/config, $XDG_CONFIG_DIR/imag/config or from env("$IMAG_CONFIG") - * and builds the Runtime object with it. - * - * The cli_spec object should be initially build with the ::get_default_cli_builder() function. - * - */ + /// Gets the CLI spec for the program and retreives the config file path (or uses the default on + /// in $HOME/.imag/config, $XDG_CONFIG_DIR/imag/config or from env("$IMAG_CONFIG") + /// and builds the Runtime object with it. + /// + /// The cli_spec object should be initially build with the ::get_default_cli_builder() function. pub fn new(mut cli_spec: App<'a, 'a>) -> Result, RuntimeError> { use std::env; use std::io::stdout; @@ -198,19 +198,19 @@ impl<'a> Runtime<'a> { .map_err_into(RuntimeErrorKind::Instantiate) } - /** - * Get a commandline-interface builder object from `clap` - * - * This commandline interface builder object already contains some predefined interface flags: - * * -v | --verbose for verbosity - * * --debug for debugging - * * -c | --config for alternative configuration file - * * -r | --rtp for alternative runtimepath - * * --store for alternative store path - * Each has the appropriate help text included. - * - * The `appname` shall be "imag-". - */ + /// + /// Get a commandline-interface builder object from `clap` + /// + /// This commandline interface builder object already contains some predefined interface flags: + /// * -v | --verbose for verbosity + /// * --debug for debugging + /// * -c | --config for alternative configuration file + /// * -r | --rtp for alternative runtimepath + /// * --store for alternative store path + /// Each has the appropriate help text included. + /// + /// The `appname` shall be "imag-". + /// pub fn get_default_cli_builder(appname: &'a str, version: &'a str, about: &'a str) @@ -279,6 +279,7 @@ impl<'a> Runtime<'a> { } + /// Get the argument names of the Runtime which are available pub fn arg_names() -> Vec<&'static str> { vec![ Runtime::arg_verbosity_name(), @@ -292,45 +293,52 @@ impl<'a> Runtime<'a> { ] } + /// Get the verbosity argument name for the Runtime pub fn arg_verbosity_name() -> &'static str { "verbosity" } + /// Get the debugging argument name for the Runtime pub fn arg_debugging_name() -> &'static str { "debugging" } + /// Get the argument name for no color output of the Runtime pub fn arg_no_color_output_name() -> &'static str { "no-color-output" } + /// Get the config argument name for the Runtime pub fn arg_config_name() -> &'static str { "config" } + /// Get the config-override argument name for the Runtime pub fn arg_config_override_name() -> &'static str { "config-override" } + /// Get the runtime argument name for the Runtime pub fn arg_runtimepath_name() -> &'static str { "runtimepath" } + /// Get the storepath argument name for the Runtime pub fn arg_storepath_name() -> &'static str { "storepath" } + /// Get the editor argument name for the Runtime pub fn arg_editor_name() -> &'static str { "editor" } + /// Get the argument name for generating the completion pub fn arg_generate_compl() -> &'static str { "generate-completion" } - /** - * Initialize the internal logger - */ + /// Initialize the internal logger fn init_logger(is_debugging: bool, is_verbose: bool, colored: bool) { use std::env::var as env_var; use env_logger; @@ -358,48 +366,37 @@ impl<'a> Runtime<'a> { } } - /** - * Get the verbosity flag value - */ + /// Get the verbosity flag value pub fn is_verbose(&self) -> bool { self.cli_matches.is_present("verbosity") } - /** - * Get the debugging flag value - */ + /// Get the debugging flag value pub fn is_debugging(&self) -> bool { self.cli_matches.is_present("debugging") } - /** - * Get the runtimepath - */ + /// Get the runtimepath pub fn rtp(&self) -> &PathBuf { &self.rtp } - /** - * Get the commandline interface matches - */ + /// Get the commandline interface matches pub fn cli(&self) -> &ArgMatches { &self.cli_matches } - /** - * Get the configuration object - */ + /// Get the configuration object pub fn config(&self) -> Option<&Configuration> { self.configuration.as_ref() } - /** - * Get the store object - */ + /// Get the store object pub fn store(&self) -> &Store { &self.store } + /// Get a editor command object which can be called to open the $EDITOR pub fn editor(&self) -> Option { self.cli() .value_of("editor")