[closes #6] added documentation everywhere

.hooks/pre-commit

@@ -6,12 +6,12 @@ make lint &> /dev/null 2>&1 || {
     exit 1;
 }
 
-branch=`git rev-parse --abbrev-ref HEAD`
+# branch=`git rev-parse --abbrev-ref HEAD`
 
-# TODO should we add release branches here as well?
+# # TODO should we add release branches here as well?
-if [[ "$branch" =~ ^master|develop$ ]]; then
+# if [[ "$branch" =~ ^master|develop$ ]]; then
-    make test > /dev/null 2>&1 || {
+#     make test > /dev/null 2>&1 || {
-        >&2 echo "Tests failed. check 'make test' for more info.";
+#         >&2 echo "Tests failed. check 'make test' for more info.";
-        exit 1;
+#         exit 1;
-    }
+#     }
-fi
+# fi

src/errors.rs

@@ -1,6 +1,9 @@
 // I can probably do this way easier using an external crate, I should do that
 use rocket::http::Status;
 
+/// Represents any general error that the API can encounter during execution.
+/// It allows us to more easily process errors, and hopefully allows for
+/// more clear error messages.
 #[derive(Debug, PartialEq)]
 pub enum FejError {
     InvalidArgument,

src/ivago/README.md

@@ -1,5 +0,0 @@
-# Ivago
-
-This part of the API is a wrapper around the Ivago website (Ivago being the
-company that collects the trash in my city). Their site isn't exactly RESTful,
-so this endpoint simply wraps it in a RESTful wrapper.

src/ivago/controller/mod.rs

@@ -20,15 +20,14 @@ const BASE_URL: &str = "https://www.ivago.be/nl/particulier/afval/ophaling";
 /// Endpoint for the actual calendar output
 const CAL_URL: &str = "https://www.ivago.be/nl/particulier/garbage/pick-up/pickups";
 
-/// Searches the Ivago API for streets in the given city
+/// Searches the Ivago API for streets in the given city.
 ///
 /// # Arguments
 ///
-/// * `street` - name of the street
+/// * `search_term` - Search term to use to look for streets
-/// * `city` - city the street is in
+pub fn search_streets(search_term: &str) -> Result<Vec<Street>, FejError> {
-pub fn search_streets(street_name: &str) -> Result<Vec<Street>, FejError> {
     let client = reqwest::Client::new();
-    let response = client.get(SEARCH_URL).query(&[("q", street_name)]).send()?;
+    let response = client.get(SEARCH_URL).query(&[("q", search_term)]).send()?;
     let data: Vec<HashMap<String, String>> = response.json()?;
 
     // This is pretty cool, filter_map first does get() on all the maps, and
@@ -41,14 +40,14 @@ pub fn search_streets(street_name: &str) -> Result<Vec<Street>, FejError> {
         .collect())
 }
 
-/// Returns the pickup times for the various trash types
+/// Returns the pickup times for the various trash types.
 ///
 /// # Arguments
 ///
-/// * `street` - desired street
+/// * `street` - Street to look up
-/// * `number` - house number
+/// * `number` - House number in given street
-/// * `start_date` - earliest date for the results
+/// * `start_date` - Earliest date for the results
-/// * `end_date` - latest date for the results
+/// * `end_date` - Latest date for the results
 pub fn get_pickup_times(
     street: &Street,
     number: &u32,

src/ivago/controller/pickup_time.rs

@@ -1,14 +1,20 @@
 use super::BasicDate;
 use serde::ser::{Serialize, SerializeStruct, Serializer};
 
-/// Represents a pickup time instance. All fields are a direct map of the
+/// Represents a date when a pickup will occur. Label describes which type of
-/// original API
+/// trash will be picked up.
 pub struct PickupTime {
     date: BasicDate,
     label: String,
 }
 
 impl PickupTime {
+    /// Creates a new PickupTime instance.
+    ///
+    /// # Arguments
+    ///
+    /// * `date` - Date of pickup time
+    /// * `label` - Type of trash
     pub fn new(date: BasicDate, label: String) -> PickupTime {
         PickupTime {
             date: date,

src/ivago/controller/street.rs

@@ -4,7 +4,7 @@ use rocket::request::FromFormValue;
 use serde::ser::{Serialize, SerializeStruct, Serializer};
 use std::convert::TryFrom;
 
-/// Represents a street
+/// Represents a street in a given city
 pub struct Street {
     name: String,
     city: String,
@@ -76,6 +76,7 @@ impl<'v> FromFormValue<'v> for Street {
 mod tests {
     use super::*;
 
+    /// Tests the conversion to string
     #[test]
     fn test_to_string() {
         let street = Street::new(String::from("testname"), String::from("city"));

src/ivago/mod.rs

@@ -9,11 +9,26 @@ pub fn routes() -> Vec<rocket::Route> {
     routes![route_search_streets, route_get_pickup_times]
 }
 
-#[get("/search?<street>")]
+/// This route handles the Ivago search endpoint. It returns a list of streets,
-pub fn route_search_streets(street: String) -> Result<Json<Vec<Street>>, Status> {
+/// consisting of a street name & a city.
-    Ok(Json(search_streets(street.as_str())?))
+///
+/// # Arguments
+///
+/// * `search_term` - Search term to use to look for streets
+#[get("/search?<search_term>")]
+pub fn route_search_streets(search_term: String) -> Result<Json<Vec<Street>>, Status> {
+    Ok(Json(search_streets(search_term.as_str())?))
 }
 
+/// Handles returning of pickup times for a specific address. It returns a list
+/// of pickup times, containing a date and a description of the trash type.
+///
+/// # Arguments
+///
+/// * `street` - Street to look up
+/// * `number` - House number in the given street
+/// * `start_date` - Earliest date that can be returned
+/// * `end_date` - Latest date that can be returned
 #[get("/?<street>&<number>&<start_date>&<end_date>")]
 pub fn route_get_pickup_times(
     street: Street,