From 9a3dbf1a4a8ec33c780e17f415a7480bcb1a0540 Mon Sep 17 00:00:00 2001 From: Aaronepower Date: Thu, 9 Jun 2016 15:35:11 +0100 Subject: [PATCH] added documentation --- src/lib/language/language_type.rs | 24 +++++- src/lib/language/languages.rs | 127 +++++++++++++++++++++++++++++- src/lib/lib.rs | 15 ++-- src/lib/lib.rs.in | 1 + src/lib/stats.rs | 17 +++- 5 files changed, 169 insertions(+), 15 deletions(-) diff --git a/src/lib/language/language_type.rs b/src/lib/language/language_type.rs index 77265f4..720d309 100644 --- a/src/lib/language/language_type.rs +++ b/src/lib/language/language_type.rs @@ -17,6 +17,8 @@ serializable_enum! { ActionScript, /// Assembly Assembly, + /// Autoconf + Autoconf, /// Bash Bash, /// Batch @@ -159,7 +161,7 @@ serializable_enum! { Yaml, /// Zsh Zsh, - /// __Total + #[doc(hidden)] __Total, } LanguageTypeVisitor @@ -180,6 +182,7 @@ impl_as_ref_from_str! { LanguageType { ActionScript => "ActionScript", Assembly => "Assembly", + Autoconf => "Autoconf", Bash => "BASH", Batch => "Batch", C => "C", @@ -258,10 +261,18 @@ impl_as_ref_from_str! { impl LanguageType { + /// Returns the display name of a language. + /// + /// ``` + /// let bash = LanguageType::Bash; + /// + /// assert_eq!(bash.name(), "BASH"); + /// ``` pub fn name(&self) -> &'static str { match *self { ActionScript => "ActionScript", Assembly => "Assembly", + Autoconf => "Autoconf", Bash => "BASH", Batch => "Batch", C => "C", @@ -337,6 +348,13 @@ impl LanguageType { } } + /// Get language from it's file extension. + /// + /// ``` + /// let rust = LanguageType::from_extension("rs"); + /// + /// assert_eq!(rust, LanguageType::Rust); + /// ``` pub fn from_extension>(entry: P) -> Option { if let Some(extension) = get_extension(entry) { match &*extension { @@ -365,6 +383,7 @@ impl LanguageType { "hs" => Some(Haskell), "html" => Some(Html), "idr" | "lidr" => Some(Idris), + "in" => Some(Autoconf), "jai" => Some(Jai), "java" => Some(Java), "jl" => Some(Julia), @@ -396,7 +415,7 @@ impl LanguageType { "r" => Some(R), "rake" | "rb" => Some(Ruby), "rhtml" => Some(RubyHtml), - "rs" | "in" => Some(Rust), + "rs" => Some(Rust), "s" => Some(Assembly), "sass" | "scss" => Some(Sass), "sc" | "scala" => Some(Scala), @@ -426,6 +445,7 @@ impl From for LanguageType { match &*from { "ActionScript" => ActionScript, "Assembly" => Assembly, + "Autoconf" => Autoconf, "Bash" => Bash, "Batch" => Batch, "C" => C, diff --git a/src/lib/language/languages.rs b/src/lib/language/languages.rs index c749d9b..cc7f72d 100644 --- a/src/lib/language/languages.rs +++ b/src/lib/language/languages.rs @@ -19,6 +19,7 @@ use super::{Language, LanguageType}; use super::LanguageType::*; use stats::Stats; +/// A collection of existing languages([_List of Languages_](https://github.com/Aaronepower/tokei#supported-languages)) #[derive(Debug, Clone)] pub struct Languages { inner: BTreeMap, @@ -26,6 +27,7 @@ pub struct Languages { impl Languages { + /// Creates a `Languages` struct from cbor. pub fn from_cbor<'a, I: Into<&'a [u8]>>(cbor: I) -> serde_cbor::Result { let map = try!(serde_cbor::from_slice(cbor.into())); @@ -33,12 +35,43 @@ impl Languages { } + /// Creates a `Languages` struct from json. + /// + /// ``` + /// let json = r#"{"Rust":{"blanks":5,"code":12,"comments":0,"stats":[{"blanks":5,"code":12,"comments":0,"lines":17,"name":".\\src\\lib\\build.rs"}],"lines":17,"total_files":1}}"#; + /// let languages = Languages::from_json(&json); + /// assert!(languages.get_mut(&LanguageType::Rust).unwrap().code == 12) + /// ``` pub fn from_json<'a, I: Into<&'a [u8]>>(json: I) -> serde_json::Result { let map = try!(serde_json::from_slice(json.into())); Ok(Self::from_previous(map)) } + /// Creates a `Languages` struct from json. + /// + /// ``` + /// let yaml = r#" + /// --- + /// "Rust": + /// "blanks": 5 + /// "code": 12 + /// "comments": 0 + /// "lines": 17 + /// "stats": + /// - + /// "blanks": 5 + /// "code": 12 + /// "comments": 0 + /// "lines": 17 + /// "name": ".\\src\\lib\\build.rs" + /// "total_files": 1 + /// "#; + /// + /// let languages = Languages::from_yaml(&yaml); + /// + /// assert!(languages.get_mut(&LanguageType::Rust).unwrap().code == 12) + /// ``` pub fn from_yaml<'a, I: Into<&'a [u8]>>(yaml: I) -> serde_yaml::Result { let map = try!(serde_yaml::from_slice(yaml.into())); @@ -49,13 +82,22 @@ impl Languages { let mut _self = Self::new(); for (name, input_language) in map { - if let Some(language) = _self.get_mut(&LanguageType::from(name)) { + if let Some(language) = _self.get_mut(&name) { *language += input_language; } } _self } + /// Get statistics from the list of paths provided, and a list ignored keywords + /// to ignore paths containing them. + /// + /// ```no_run + /// let languages = Languages::new(); + /// languages.get_statistics(&vec!["."], &vec![".git", "target"]); + /// + /// println!("{:?}", languages); + /// ``` pub fn get_statistics<'a, I>(&mut self, paths: I, ignored: I) where I: Into> { @@ -157,11 +199,17 @@ impl Languages { }); } + /// Constructs a new, blank `Languages`. + /// + /// ``` + /// let languages = Languages::new(); + /// ``` pub fn new() -> Self { use super::LanguageType::*; let map = btreemap! { ActionScript => Language::new_c(), Assembly => Language::new_single(vec![";"]), + Autoconf => Language::new_single(vec!["#", "dnl"]), Bash => Language::new_hash(), Batch => Language::new_single(vec!["REM"]), C => Language::new_c(), @@ -246,7 +294,7 @@ impl Languages { } fn remove_empty(&self) -> BTreeMap { - let mut map: BTreeMap = BTreeMap::new(); + let mut map = BTreeMap::new(); for (name, language) in &self.inner { if !language.is_empty() { @@ -256,12 +304,62 @@ impl Languages { map } + /// Converts `Languages` to CBOR. + /// + /// ```no_run + /// extern crate rustc_serialize; + /// use rustc_serialize::ToHex; + /// + /// let cbor = "a16452757374a666626c616e6b730564636f64650c68636f6d6d656e74730\ + /// 065737461747381a566626c616e6b730564636f64650c68636f6d6d656e747300656c\ + /// 696e657311646e616d65722e5c7372635c6c69625c6275696c642e7273656c696e657\ + /// 3116b746f74616c5f66696c657301"; + /// + /// let languages = Languages::new(); + /// languages.get_statistics(&vec!["src/lib/build.rs"], &vec![".git"]); + /// + /// assert_eq!(cbor, languages.to_cbor().to_hex()); + /// ``` pub fn to_cbor(&self) -> Result, serde_cbor::Error> { serde_cbor::to_vec(&self.remove_empty()) } + + /// Converts `Languages` to JSON. + /// + /// ```no_run + /// + /// let json = r#"{"Rust":{"blanks":5,"code":12,"comments":0,"stats":[{"blanks":5,"code":12,"comments":0,"lines":17,"name":".\\src\\lib\\build.rs"}],"lines":17,"total_files":1}}"#; + /// let languages = Languages::new(); + /// languages.get_statistics(&vec!["src/lib/build.rs"], &vec![".git"]); + /// + /// assert_eq!(json, languages.to_json()); + /// ``` pub fn to_json(&self) -> Result { serde_json::to_string(&self.remove_empty()) } + /// Converts `Languages` to YAML. + /// + /// ```no_run + /// + /// let yaml = r#" + /// --- + /// "Rust": + /// "blanks": 5 + /// "code": 12 + /// "comments": 0 + /// "lines": 17 + /// "stats": + /// - + /// "blanks": 5 + /// "code": 12 + /// "comments": 0 + /// "lines": 17 + /// "name": ".\\src\\lib\\build.rs" + /// "total_files": 1"#; + /// let languages = Languages::new(); + /// languages.get_statistics(&vec!["src/lib/build.rs"], &vec![".git"]); + /// + /// assert_eq!(yaml, languages.to_yaml()); pub fn to_yaml(&self) -> Result { serde_yaml::to_string(&self.remove_empty()) } @@ -306,6 +404,31 @@ impl AddAssign> for Languages { } } +impl<'a> AddAssign<&'a BTreeMap> for Languages { + fn add_assign(&mut self, rhs: &'a BTreeMap) { + + for (name, language) in rhs { + + if let Some(result) = self.inner.get_mut(&name) { + *result += language; + } + } + } +} + +impl<'a> AddAssign<&'a mut BTreeMap> for Languages { + fn add_assign(&mut self, rhs: &'a mut BTreeMap) { + + for (name, language) in rhs { + + if let Some(result) = self.inner.get_mut(&name) { + *result += language; + } + } + } +} + + impl Deref for Languages { type Target = BTreeMap; diff --git a/src/lib/lib.rs b/src/lib/lib.rs index ead38b9..25ae432 100644 --- a/src/lib/lib.rs +++ b/src/lib/lib.rs @@ -1,13 +1,12 @@ -#![deny(missing_docs, - missing_debug_implementations, missing_copy_implementations, - trivial_casts, trivial_numeric_casts, - unsafe_code, - unstable_features, - unused_import_braces)] + #![deny(missing_debug_implementations, missing_copy_implementations, + trivial_casts, trivial_numeric_casts, + unsafe_code, + unstable_features, + unused_import_braces)] -//! # Tokei: Code Analysis Library(For the [binary](https://github.com/Aaronepower/tokei/)) +//! # Tokei: Code Analysis Library([For the binary](https://github.com/Aaronepower/tokei/)) //! -//! Tokei is the library powering the application of the same name. +//! Tokei is a code analysis library powering the application of the same name. #[macro_use] extern crate maplit; diff --git a/src/lib/lib.rs.in b/src/lib/lib.rs.in index 3f840e7..d75b8c1 100644 --- a/src/lib/lib.rs.in +++ b/src/lib/lib.rs.in @@ -1,5 +1,6 @@ #[macro_use] +#![allow(missing_docs)] mod utils; mod language; mod stats; diff --git a/src/lib/stats.rs b/src/lib/stats.rs index 6e809bb..c424949 100644 --- a/src/lib/stats.rs +++ b/src/lib/stats.rs @@ -1,16 +1,27 @@ use std::fmt; +/// A struct representing the statistics of a file. #[derive(Clone, Default, Debug, Deserialize, Eq, Ord, PartialEq, PartialOrd, Serialize)] pub struct Stats { - pub name: String, - pub code: usize, + /// Number of blank lines within the file. pub blanks: usize, - pub lines: usize, + /// Number of lines of code within the file. + pub code: usize, + /// Number of comments within the file. (_includes both multi line, and single line comments_) pub comments: usize, + /// Total number of lines within the file. + pub lines: usize, + /// File name. + pub name: String, } impl Stats { + /// Create a new `Stats` from a file path. + /// + /// ``` + /// let stats = Stats::new("src/main.rs"); + /// ``` pub fn new>(name: S) -> Self { Stats { name: name.into(), ..Self::default() } }