Merge pull request #8 from matthiasbeyer/doc

Doc

5 files changed, 46 insertions, 58 deletions

diff --git a/src/backend.rs b/src/backend.rs
index 57afd10..fe1fa7e 100644
--- a/src/backend.rs
+++ b/src/backend.rs
@@ -3,8 +3,8 @@ use failure::Fallible as Result;
 
 use librepology::v1::api::Api;
 use librepology::v1::restapi::RestApi;
+use librepology::v1::stdinapi::StdinWrapper;
 use librepology::v1::types::*;
-use librepology::v1::api::StdinWrapper;
 
 use crate::config::Configuration;
 
@@ -15,6 +15,9 @@ pub enum Backend {
     RepologyOrg(RestApi),
 }
 
+/// Implement Api for Backend
+///
+/// With this, we can use the `Backend` object and do not have to care whether we have a librepology::
 impl Api for Backend {
     fn project<N: AsRef<str>>(&self, name: N) -> Result<Vec<Package>> {
         match self {
diff --git a/src/frontend/json.rs b/src/frontend/json.rs
index cd7e651..39e86f8 100644
--- a/src/frontend/json.rs
+++ b/src/frontend/json.rs
@@ -15,23 +15,34 @@ use librepology::v1::api::Api;
 
 pub struct JsonFrontend(Stdout);
 
+/// A Frontend that serializes the data to JSON
+///
+/// Useful for piping the data as structured data to another program.
+///
+/// # Warning
+///
+/// This frontend does _not_ maintain compatibility with repolocli itself. That means that piping
+/// output from repolocli to repolocli is _NOT_ supported by this frontend.
+///
 impl JsonFrontend {
     pub fn new(stdout: Stdout) -> Self {
         JsonFrontend(stdout)
     }
+
+    fn write(&self, output: String) -> Result<()> {
+        let mut outlock = self.0.lock();
+        writeln!(outlock, "{}", output).map_err(Error::from)
+    }
 }
 
 impl Frontend for JsonFrontend {
     fn list_packages(&self, packages: Vec<Package>) -> Result<()> {
-        let output = serde_json::ser::to_string_pretty(&packages).map_err(Error::from)?;
-        let mut outlock = self.0.lock();
-        writeln!(outlock, "{}", output).map_err(Error::from)
+        self.write(serde_json::ser::to_string_pretty(&packages).map_err(Error::from)?)
+
     }
 
     fn list_problems(&self, problems: Vec<Problem>) -> Result<()> {
-        let output = serde_json::ser::to_string_pretty(&problems).map_err(Error::from)?;
-        let mut outlock = self.0.lock();
-        writeln!(outlock, "{}", output).map_err(Error::from)
+        self.write(serde_json::ser::to_string_pretty(&problems).map_err(Error::from)?)
     }
 
     fn compare_packages(&self, packages: Vec<ComparePackage>, backend: &Backend, filter_repos: Vec<Repo>) -> Result<()> {
@@ -71,10 +82,7 @@ impl Frontend for JsonFrontend {
             });
         }
 
-        let output = serde_json::ser::to_string_pretty(&output)?;
-
-        let mut outlock = self.0.lock();
-        writeln!(outlock, "{}", output).map_err(Error::from)
+        self.write(serde_json::ser::to_string_pretty(&output)?)
     }
 }
 
diff --git a/src/frontend/list.rs b/src/frontend/list.rs
index e870ab0..e4ed7d7 100644
--- a/src/frontend/list.rs
+++ b/src/frontend/list.rs
@@ -15,6 +15,9 @@ use librepology::v1::api::Api;
 
 pub struct ListFrontend(Stdout);
 
+/// A Frontend that prints the data in a human-readable way but without ASCII-art.
+///
+/// It seperates the values with dashes ("-") for a slightly better reading experience.
 impl ListFrontend {
     pub fn new(stdout: Stdout) -> Self {
         ListFrontend(stdout)
diff --git a/src/frontend/mod.rs b/src/frontend/mod.rs
index 43e5b5e..3bb912c 100644
--- a/src/frontend/mod.rs
+++ b/src/frontend/mod.rs
@@ -10,6 +10,7 @@ use crate::frontend::table::TableFrontend;
 use crate::compare::ComparePackage;
 use crate::backend::Backend;
 
+/// A Frontend represents a way to show the data to the user
 pub trait Frontend {
     fn list_packages(&self, packages: Vec<Package>) -> Result<()>;
     fn list_problems(&self, problems: Vec<Problem>) -> Result<()>;
@@ -20,6 +21,7 @@ pub mod list;
 pub mod json;
 pub mod table;
 
+/// Helper function for building a new Frontend object based on the commandline parameters
 pub fn new_frontend(app: &ArgMatches, _config: &Configuration) -> Result<Box<Frontend>> {
     match app.value_of("output") {
         None | Some("lines") => {
diff --git a/src/frontend/table.rs b/src/frontend/table.rs
index 6a30e9c..35c867c 100644
--- a/src/frontend/table.rs
+++ b/src/frontend/table.rs
@@ -13,16 +13,15 @@ use crate::backend::Backend;
 use crate::compare::ComparePackage;
 use librepology::v1::api::Api;
 
+/// A Frontend that formats the output in a nice ASCII-art table
 pub struct TableFrontend(Stdout);
 
 impl TableFrontend {
     pub fn new(stdout: Stdout) -> Self {
         TableFrontend(stdout)
     }
-}
 
-impl Frontend for TableFrontend {
-    fn list_packages(&self, packages: Vec<Package>) -> Result<()> {
+    fn mktable(&self) -> Table {
         let mut table = Table::new();
         let format = format::FormatBuilder::new()
             .column_separator('|')
@@ -34,9 +33,20 @@ impl Frontend for TableFrontend {
             .padding(1, 1)
             .build();
         table.set_format(format);
-
         table.set_titles(row!["Name", "Version", "Repo", "Status", "URL"]);
+        table
+    }
+
+    fn print(&self, table: Table) -> Result<()> {
+        let mut outlock = self.0.lock();
+        table.print(&mut outlock)?;
+        Ok(())
+    }
+}
 
+impl Frontend for TableFrontend {
+    fn list_packages(&self, packages: Vec<Package>) -> Result<()> {
+        let mut table = self.mktable();
         packages.iter().for_each(|package| {
             let status = if let Some(stat) = package.status() {
                 format!("{}", stat)
@@ -56,28 +66,11 @@ impl Frontend for TableFrontend {
 
             table.add_row(row![package.name(), package.version(), package.repo(), status, url]);
         });
-
-        let mut outlock = self.0.lock();
-        table.print(&mut outlock)?;
-
-        Ok(())
+        self.print(table)
     }
 
     fn list_problems(&self, problems: Vec<Problem>) -> Result<()> {
-        let mut table = Table::new();
-        let format = format::FormatBuilder::new()
-            .column_separator('|')
-            .borders('|')
-            .separators(
-                &[format::LinePosition::Title, format::LinePosition::Top, format::LinePosition::Bottom],
-                format::LineSeparator::new('-', '+', '+', '+')
-            )
-            .padding(1, 1)
-            .build();
-        table.set_format(format);
-
-        table.set_titles(row!["Repo", "Name", "EffName", "Maintainer", "Description"]);
-
+        let mut table = self.mktable();
         problems.iter().for_each(|problem| {
             trace!("Adding row for: {:?}", problem);
             table.add_row(row![
@@ -88,28 +81,11 @@ impl Frontend for TableFrontend {
                 problem.problem_description()
             ]);
         });
-
-        let mut outlock = self.0.lock();
-        table.print(&mut outlock)?;
-
-        Ok(())
+        self.print(table)
     }
 
     fn compare_packages(&self, packages: Vec<ComparePackage>, backend: &Backend, filter_repos: Vec<Repo>) -> Result<()> {
-        let mut table = Table::new();
-        let format = format::FormatBuilder::new()
-            .column_separator('|')
-            .borders('|')
-            .separators(
-                &[format::LinePosition::Title, format::LinePosition::Top, format::LinePosition::Bottom],
-                format::LineSeparator::new('-', '+', '+', '+')
-            )
-            .padding(1, 1)
-            .build();
-        table.set_format(format);
-
-        table.set_titles(row!["Name", "Local Version", "Repo", "Upstream Version"]);
-
+        let mut table = self.mktable();
         for package in packages {
             backend
                 .project(package.name().deref())?
@@ -124,11 +100,7 @@ impl Frontend for TableFrontend {
                    ]);
                 });
         }
-
-        let mut outlock = self.0.lock();
-        table.print(&mut outlock)?;
-
-        Ok(())
+        self.print(table)
     }
 }