Merge pull request #9 from matthiasbeyer/doc

Document all the things

5 files changed, 36 insertions, 0 deletions

diff --git a/src/duration.rs b/src/duration.rs
index d080584..6de4c49 100644
--- a/src/duration.rs
+++ b/src/duration.rs
@@ -5,17 +5,23 @@ use std::fmt::{Display, Error, Formatter};
 use std::ops::{Add, Deref};
 use std::str::FromStr;
 
+/// Duration type
+///
+/// A type that represents a duration of time
 #[derive(Clone, Debug)]
 pub struct IcalDuration {
     duration: ical::icaldurationtype,
 }
 
 impl IcalDuration {
+
+    /// Convert a number of seconds to an IcalDuration
     pub fn from_seconds(seconds: i32) -> IcalDuration {
         let duration = unsafe { ical::icaldurationtype_from_int(seconds) };
         IcalDuration { duration }
     }
 
+    /// Get the number of seconds the IcalDuration represents
     pub fn to_seconds(&self) -> i32 {
         unsafe { ical::icaldurationtype_as_int(self.duration) }
     }
diff --git a/src/lib.rs b/src/lib.rs
index 71579d8..d0fc056 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,3 +1,11 @@
+//! libical high level interface
+//!
+//! This library offers a high-level interface for the widely used libical. It relies upon the
+//! libical-sys crate, which is a thin rust layer over the libical C API.
+//! It provides a safe interface to libical that is rather lower-level, as well as convenience
+//! functionality build on this low-level interface for easy handling of icalendar data.
+//!
+
 #![warn(unused_extern_crates)]
 #![allow(clippy::redundant_closure)] // disable "redundant closure" lint
 
@@ -48,3 +56,4 @@ pub use crate::timezone::IcalTimeZone;
 pub use crate::vcalendar::IcalEventIter;
 pub use crate::vcalendar::IcalVCalendar;
 pub use crate::vevent::IcalVEvent;
+
diff --git a/src/property.rs b/src/property.rs
index 55b5914..63e7540 100644
--- a/src/property.rs
+++ b/src/property.rs
@@ -5,6 +5,9 @@ use std::fmt;
 use super::component::IcalComponent;
 use crate::ical;
 
+/// A property in the ical data
+///
+/// This type represents a single property (name + value).
 pub struct IcalProperty<'a> {
     pub ptr: *mut ical::icalproperty,
     _parent: &'a dyn IcalComponent,
diff --git a/src/time.rs b/src/time.rs
index 28a94a1..f40ded3 100644
--- a/src/time.rs
+++ b/src/time.rs
@@ -9,20 +9,27 @@ use std::fmt::{Display, Error, Formatter};
 use std::ops::{Add, Deref};
 use std::str::FromStr;
 
+/// Time type
+///
+/// A type representing "time"
 #[derive(Clone, Debug)]
 pub struct IcalTime {
     time: ical::icaltimetype,
 }
 
 impl IcalTime {
+
+    /// Get an IcalTime object that represents UTC now
     pub fn utc() -> Self {
         dateutil::now().into()
     }
 
+    /// Get an IcalTime object that represents the current time in the local timezone.
     pub fn local() -> Self {
         dateutil::now().with_timezone(&Local).into()
     }
 
+    /// Get an IcalTime object that represents a specific day.
     pub fn floating_ymd(year: i32, month: i32, day: i32) -> Self {
         let time = ical::icaltimetype {
             year,
@@ -39,6 +46,8 @@ impl IcalTime {
         IcalTime { time }
     }
 
+    /// Get an IcalTime object that is the same as the object this function is called on, but with
+    /// hour, minute and second set
     pub fn and_hms(&self, hour: i32, minute: i32, second: i32) -> Self {
         let mut time = self.time;
         time.hour = hour;
@@ -51,6 +60,7 @@ impl IcalTime {
         IcalTime { time }
     }
 
+    /// Get an IcalTime object based on a timestamp
     pub fn from_timestamp(timestamp: i64) -> Self {
         let _lock = TZ_MUTEX.lock();
         let utc = IcalTimeZone::utc();
@@ -59,21 +69,25 @@ impl IcalTime {
         IcalTime { time }
     }
 
+    /// Get the timestamp representation of the IcalTime object
     pub fn timestamp(&self) -> i64 {
         let _lock = TZ_MUTEX.lock();
         unsafe { ical::icaltime_as_timet_with_zone(self.time, self.time.zone) }
     }
 
+    /// Get whether the IcalTime object is a date object
     pub fn is_date(&self) -> bool {
         self.time.is_date != 0
     }
 
+    /// Get the IcalTime object as a date object
     pub fn as_date(&self) -> IcalTime {
         let mut time = self.time;
         time.is_date = 1;
         IcalTime { time }
     }
 
+    /// Get the timezone for the IcalTime object
     pub fn get_timezone(&self) -> Option<IcalTimeZone> {
         if self.time.zone.is_null() {
             return None;
@@ -82,6 +96,7 @@ impl IcalTime {
         Some(IcalTimeZone::from_ptr_copy(tz_ptr))
     }
 
+    /// Get a new IcalTime object with a different timezone
     pub fn with_timezone(&self, timezone: &IcalTimeZone) -> IcalTime {
         let _lock = TZ_MUTEX.lock();
         let mut time = unsafe { ical::icaltime_convert_to_zone(self.time, **timezone) };
@@ -90,6 +105,7 @@ impl IcalTime {
         IcalTime { time }
     }
 
+    /// Get a new IcalTime object with the day before the day of the current object
     pub fn pred(&self) -> IcalTime {
         let mut time = self.time;
         time.day -= 1;
@@ -97,6 +113,7 @@ impl IcalTime {
         IcalTime { time }
     }
 
+    /// Get a new IcalTime object with the day after the day of the current object
     pub fn succ(&self) -> IcalTime {
         let mut time = self.time;
         time.day += 1;
diff --git a/src/timezone.rs b/src/timezone.rs
index 843a1ed..855b9da 100644
--- a/src/timezone.rs
+++ b/src/timezone.rs
@@ -5,6 +5,7 @@ use std::ops::Deref;
 use super::IcalTime;
 use crate::utils::dateutil;
 
+/// A type representing a timezone.
 pub struct IcalTimeZone {
     timezone: *mut ical::icaltimezone,
 }