Merge pull request #19 from matthiasbeyer/add-documentation

[WIP] Add documentation

11 files changed, 166 insertions, 12 deletions

diff --git a/src/annotation.rs b/src/annotation.rs
index 7d0ff83..d50aca6 100644
--- a/src/annotation.rs
+++ b/src/annotation.rs
@@ -1,3 +1,5 @@
+//! Module containing types and functions for annotations of tasks
+
 use std::result::Result as RResult;
 
 use serde::Serialize;
@@ -11,6 +13,9 @@ use serde::de::MapVisitor as DeserializeMapVisitor;
 
 use date::Date;
 
+/// Annotation type for task annotations.
+/// Each annotation in taskwarrior consists of a date and a description,
+/// the date is named "entry", the description "description" in the JSON export.
 #[derive(Clone, Debug)]
 pub struct Annotation {
     entry: Date,
@@ -19,6 +24,7 @@ pub struct Annotation {
 
 impl Annotation {
 
+    /// Create a new Annotation object
     pub fn new(entry: Date, description: String) -> Annotation {
         Annotation {
             entry: entry,
@@ -26,10 +32,12 @@ impl Annotation {
         }
     }
 
+    /// Get the entry date
     pub fn entry(&self) -> &Date {
         &self.entry
     }
 
+    /// Get the description text
     pub fn description(&self) -> &String {
         &self.description
     }
@@ -49,6 +57,7 @@ impl Serialize for Annotation {
 
 }
 
+/// Helper type for the `Serialize` implementation
 struct AnnotationVisitor<'a> {
     value: &'a Annotation,
     state: u8,
@@ -91,6 +100,7 @@ impl Deserialize for Annotation {
 
 }
 
+/// Helper type for the `Deserialize` implementation
 struct AnnotationDeserializeVisitor;
 
 impl Visitor for AnnotationDeserializeVisitor {
diff --git a/src/date.rs b/src/date.rs
index ec3bef5..ee91a81 100644
--- a/src/date.rs
+++ b/src/date.rs
@@ -1,4 +1,7 @@
+//! Module for wrapping chrono::naive::datetime::NaiveDateTime
+
 use std::error::Error;
+use std::ops::{Deref, DerefMut};
 
 use serde::Serialize;
 use serde::Serializer;
@@ -8,9 +11,27 @@ use serde::de::Visitor;
 use serde::de::Error as SerdeError;
 use chrono::naive::datetime::NaiveDateTime;
 
+/// Date is a NaiveDateTime-Wrapper object to be able to implement foreign traits on it
 #[derive(Clone, Debug, Hash, Eq, PartialEq)]
 pub struct Date(NaiveDateTime);
 
+impl Deref for Date {
+    type Target = NaiveDateTime;
+
+    fn deref(&self) -> &NaiveDateTime {
+        &self.0
+    }
+
+}
+
+impl DerefMut for Date {
+
+    fn deref_mut(&mut self) -> &mut NaiveDateTime {
+        &mut self.0
+    }
+
+}
+
 impl From<NaiveDateTime> for Date {
 
     fn from(ndt: NaiveDateTime) -> Date {
@@ -19,6 +40,7 @@ impl From<NaiveDateTime> for Date {
 
 }
 
+/// The date-time parsing template used to parse the date time data exported by taskwarrior.
 pub static TASKWARRIOR_DATETIME_TEMPLATE : &'static str = "%Y%m%dT%H%M%SZ";
 
 impl Serialize for Date {
diff --git a/src/error.rs b/src/error.rs
index 90c894c..78eaddc 100644
--- a/src/error.rs
+++ b/src/error.rs
@@ -1,14 +1,19 @@
+//! Error module, containing error types
+
 use std::error::Error;
 use std::fmt::Error as FmtError;
 use std::clone::Clone;
 use std::fmt::{Display, Formatter};
 
-/**
- * Kind of store error
- */
+///
+/// Kind of task error
+///
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub enum TaskErrorKind {
+    /// Error kind indicating that the JSON parser failed
     ParserError,
+
+    /// Error kind indicating that the Status of a task is missing
     NoStatus,
 }
 
@@ -28,9 +33,9 @@ impl Display for TaskErrorKind {
 
 }
 
-/**
- * Store error type
- */
+///
+/// Task error type
+///
 #[derive(Debug)]
 pub struct TaskError {
     err_type: TaskErrorKind,
@@ -39,9 +44,9 @@ pub struct TaskError {
 
 impl TaskError {
 
-    /**
-     * Build a new TaskError from an TaskErrorKind, optionally with cause
-     */
+    ///
+    /// Build a new TaskError from an TaskErrorKind, optionally with cause
+    ///
     pub fn new(errtype: TaskErrorKind, cause: Option<Box<Error>>)
         -> TaskError
         {
@@ -51,9 +56,9 @@ impl TaskError {
             }
         }
 
-    /**
-     * Get the error type of this TaskError
-     */
+    ///
+    /// Get the error type of this TaskError
+    ///
     pub fn err_type(&self) -> TaskErrorKind {
         self.err_type.clone()
     }
diff --git a/src/import.rs b/src/import.rs
index 2bd3237..be4760c 100644
--- a/src/import.rs
+++ b/src/import.rs
@@ -1,3 +1,5 @@
+//! Module containing the `import()` function
+
 use std::io::Read;
 
 use serde_json;
@@ -6,6 +8,8 @@ use result::Result;
 use task::Task;
 use error::{TaskError, TaskErrorKind};
 
+/// Import taskwarrior-exported JSON. This expects an JSON Array of objects, as exported by
+/// taskwarrior.
 pub fn import<R: Read>(r: R) -> Result<Vec<Task>> {
     serde_json::from_reader(r)
         .map_err(|e| {
diff --git a/src/lib.rs b/src/lib.rs
index 5abb16d..7afe065 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,3 +1,26 @@
+//! This crate exports functionality to import and export taskwarrior-compatible JSON by
+//! translating the JSON into rust types and vice-versa.
+//!
+//! For example:
+//!
+//! ```
+//!   use std::io::stdin;
+//!
+//!   use task_hookrs::task::Task;
+//!   use task_hookrs::import::import;
+//!
+//!   if let Ok(tasks) = import(stdin()) {
+//!       for task in tasks {
+//!           println!("Task: {}, entered {:?} is {} -> {}",
+//!                     task.uuid(),
+//!                     task.entry(),
+//!                     task.status(),
+//!                     task.description());
+//!       }
+//!   }
+//! ```
+//!
+#![deny(missing_docs)]
 #![doc(html_root_url = "https://matthiasbeyer.github.io/task-hookrs/")]
 #![deny(
     dead_code,
diff --git a/src/priority.rs b/src/priority.rs
index 323cdd6..16b1c74 100644
--- a/src/priority.rs
+++ b/src/priority.rs
@@ -1,3 +1,5 @@
+//! Module containing TaskPriority types and trait impls
+
 use serde::Serialize;
 use serde::ser::Serializer;
 use serde::de::Deserialize;
@@ -5,10 +7,16 @@ use serde::de::Deserializer;
 use serde::Error;
 use serde::de::Visitor;
 
+/// Enum for the priorities taskwarrior supports.
 #[derive(Debug, Clone, PartialEq)]
 pub enum TaskPriority {
+    /// Low prio for a Task
     Low,
+
+    /// Medium prio for a Task
     Medium,
+
+    /// High prio for a Task
     High,
 }
 
diff --git a/src/project.rs b/src/project.rs
index 82a1d68..1bebbeb 100644
--- a/src/project.rs
+++ b/src/project.rs
@@ -1,2 +1,5 @@
+//! Module containing `Project` type
+
+/// Typedef for Project type.
 pub type Project = String;
 
diff --git a/src/result.rs b/src/result.rs
index db95026..f450c5a 100644
--- a/src/result.rs
+++ b/src/result.rs
@@ -1,5 +1,8 @@
+//! Module containing `Result` type
+
 use std::result::Result as RResult;
 
 use error::TaskError;
 
+/// Result type wrapping the standard std::result::Result type
 pub type Result<T> = RResult<T, TaskError>;
diff --git a/src/status.rs b/src/status.rs
index 8333c66..4fa90a9 100644
--- a/src/status.rs
+++ b/src/status.rs
@@ -1,3 +1,8 @@
+//! Module containing `TaskStatus` type and trait impls
+
+use std::fmt::{Display, Formatter};
+use std::fmt::Error as FmtError;
+
 use serde::Serialize;
 use serde::Serializer;
 use serde::Deserialize;
@@ -5,15 +10,38 @@ use serde::Deserializer;
 use serde::de::Error;
 use serde::de::Visitor;
 
+/// Enum for status taskwarrior supports.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub enum TaskStatus {
+    /// Pening status type
     Pending,
+
+    /// Deleted status type
     Deleted,
+
+    /// Completed status type
     Completed,
+
+    /// Waiting status type
     Waiting,
+
+    /// Recurring status type
     Recurring
 }
 
+impl Display for TaskStatus {
+
+    fn fmt(&self, fmt: &mut Formatter) -> Result<(), FmtError> {
+        match self {
+            &TaskStatus::Pending   => write!(fmt, "Pending"),
+            &TaskStatus::Deleted   => write!(fmt, "Deleted"),
+            &TaskStatus::Completed => write!(fmt, "Completed"),
+            &TaskStatus::Waiting   => write!(fmt, "Waiting"),
+            &TaskStatus::Recurring => write!(fmt, "Recurring"),
+        }
+    }
+}
+
 impl Serialize for TaskStatus {
 
     fn serialize<S>(&self, serializer: &mut S) -> Result<(), S::Error>
diff --git a/src/tag.rs b/src/tag.rs
index cba2322..1c8ae82 100644
--- a/src/tag.rs
+++ b/src/tag.rs
@@ -1 +1,4 @@
+//! Module containing `Tag` type
+
+/// type definition for tags
 pub type Tag = String;
diff --git a/src/task.rs b/src/task.rs
index 8aaae17..371078d 100644
--- a/src/task.rs
+++ b/src/task.rs
@@ -1,3 +1,5 @@
+//! Module containing `Task` type as well as trait implementations
+
 use std::result::Result as RResult;
 
 use serde::Serialize;
@@ -17,6 +19,20 @@ use tag::Tag;
 use date::Date;
 use annotation::Annotation;
 
+/// Task type
+///
+/// A task must have four things:
+///
+/// - A Status
+/// - An UUID
+/// - An Entry-Date
+/// - A Description
+///
+/// all other Data is optional by taskwarrior. This type is a simple rust representation of the
+/// JSON exported by taskwarrior.
+///
+/// It is deserializeable and serializeable via serde_json, so importing and exporting taskwarrior
+/// tasks is simply serializing and deserializing objects of this type.
 #[derive(Debug, Clone)]
 pub struct Task {
     status      : TaskStatus,
@@ -48,6 +64,7 @@ pub struct Task {
  */
 impl Task {
 
+    /// Create a new Task instance
     pub fn new(
         status      : TaskStatus,
         uuid        : Uuid,
@@ -97,26 +114,32 @@ impl Task {
         }
     }
 
+    /// Get the status of the task
     pub fn status(&self) -> &TaskStatus {
         &self.status
     }
 
+    /// Get the uuid of the task
     pub fn uuid(&self) -> &Uuid {
         &self.uuid
     }
 
+    /// Get the entry date of the task
     pub fn entry(&self) -> &Date {
         &self.entry
     }
 
+    /// Get the description of the task
     pub fn description(&self) -> &String {
         &self.description
     }
 
+    /// Get the annotations of the task
     pub fn annotations(&self) -> Option<&Vec<Annotation>> {
         self.annotations.as_ref()
     }
 
+    /// Add an annotation to this task
     pub fn add_annotation(&mut self, an: Annotation) {
         if self.annotations.is_none() {
             self.annotations = Some(vec![an]);
@@ -128,68 +151,88 @@ impl Task {
         }
     }
 
+    /// Add annotations to this task
     pub fn add_annotations<I: Iterator<Item = Annotation>>(&mut self, i: I) {
         for item in i {
             self.add_annotation(item)
         }
     }
 
+    /// Get the depends of the task
+    ///
+    /// This is exported as String by now, which might change in future
     pub fn depends(&self) -> Option<&String> {
         self.depends.as_ref()
     }
 
+    /// Get the due date of the task
     pub fn due(&self) -> Option<&Date> {
         self.due.as_ref()
     }
 
+    /// Get the end date of the task
     pub fn end(&self) -> Option<&Date> {
         self.end.as_ref()
     }
 
+    /// Get the imask of the task
     pub fn imask(&self) -> Option<&i64> {
         self.imask.as_ref()
     }
 
+    /// Get the mask of the task
     pub fn mask(&self) -> Option<&String> {
         self.mask.as_ref()
     }
 
+    /// Get the modified date of the task
     pub fn modified(&self) -> Option<&Date> {
         self.modified.as_ref()
     }
 
+    /// Get the parent of the task
     pub fn parent(&self) -> Option<&Uuid> {
         self.parent.as_ref()
     }
 
+    /// Get the priority of the task
     pub fn priority(&self) -> Option<&TaskPriority> {
         self.priority.as_ref()
     }
 
+    /// Get the project of the task
     pub fn project(&self) -> Option<&Project> {
         self.project.as_ref()
     }
 
+    /// Get the recur of the task
+    ///
+    /// This is exported as String by now. This might change in future versions of this crate.
     pub fn recur(&self) -> Option<&String> {
         self.recur.as_ref()
     }
 
+    /// Get the scheduled date of the task
     pub fn scheduled(&self) -> Option<&Date> {
         self.scheduled.as_ref()
     }
 
+    /// Get the start date of the task
     pub fn start(&self) -> Option<&Date> {
         self.start.as_ref()
     }
 
+    /// Get the tags of the task
     pub fn tags(&self) -> Option<&Vec<Tag>> {
         self.tags.as_ref()
     }
 
+    /// Get the until date of the task
     pub fn until(&self) -> Option<&Date> {
         self.until.as_ref()
     }
 
+    /// Get the wait date of the task
     pub fn wait(&self) -> Option<&Date> {
         self.wait.as_ref()
     }
@@ -209,6 +252,7 @@ impl Serialize for Task {
 
 }
 
+/// Helper type for task serialization
 struct TaskVisitor<'a> {
     value: &'a Task,
     state: u8,
@@ -341,6 +385,7 @@ impl Deserialize for Task {
 
 }
 
+/// Helper type for task deserialization
 struct TaskDeserializeVisitor;
 
 impl Visitor for TaskDeserializeVisitor {