src: Add back-referencing comments to route handler functions

These comments should be further extended with input/output definitions and examples

Author: Turbo87

src/keyword.rs

@@ -139,6 +139,7 @@ impl Model for Keyword {
     fn table_name(_: Option<Keyword>) -> &'static str { "keywords" }
 }
 
+/// Handles the `GET /keywords` route.
 pub fn index(req: &mut Request) -> CargoResult<Response> {
     let conn = try!(req.tx());
     let (offset, limit) = try!(req.pagination(10, 100));
@@ -175,6 +176,7 @@ pub fn index(req: &mut Request) -> CargoResult<Response> {
     }))
 }
 
+/// Handles the `GET /keywords/:keyword_id` route.
 pub fn show(req: &mut Request) -> CargoResult<Response> {
     let name = &req.params()["keyword_id"];
     let conn = try!(req.tx());
@@ -185,4 +187,3 @@ pub fn show(req: &mut Request) -> CargoResult<Response> {
     struct R { keyword: EncodableKeyword }
     Ok(req.json(&R { keyword: kw.encodable() }))
 }
-

src/krate.rs

@@ -452,6 +452,7 @@ impl Model for Crate {
     fn table_name(_: Option<Crate>) -> &'static str { "crates" }
 }
 
+/// Handles the `GET /crates` route.
 #[allow(trivial_casts)]
 pub fn index(req: &mut Request) -> CargoResult<Response> {
     let conn = try!(req.tx());
@@ -574,6 +575,7 @@ pub fn index(req: &mut Request) -> CargoResult<Response> {
     }))
 }
 
+/// Handles the `GET /summary` route.
 pub fn summary(req: &mut Request) -> CargoResult<Response> {
     let tx = try!(req.tx());
     let num_crates = {
@@ -620,6 +622,7 @@ pub fn summary(req: &mut Request) -> CargoResult<Response> {
     }))
 }
 
+/// Handles the `GET /crates/:crate_id` route.
 pub fn show(req: &mut Request) -> CargoResult<Response> {
     let name = &req.params()["crate_id"];
     let conn = try!(req.tx());
@@ -643,6 +646,7 @@ pub fn show(req: &mut Request) -> CargoResult<Response> {
     }))
 }
 
+/// Handles the `PUT /crates/new` route.
 pub fn new(req: &mut Request) -> CargoResult<Response> {
     let app = req.app().clone();
 
@@ -817,6 +821,7 @@ fn read_fill<R: Read + ?Sized>(r: &mut R, mut slice: &mut [u8])
     Ok(())
 }
 
+/// Handles the `GET /crates/:crate_id/:version/download` route.
 pub fn download(req: &mut Request) -> CargoResult<Response> {
     let crate_name = &req.params()["crate_id"];
     let version = &req.params()["version"];
@@ -872,6 +877,7 @@ pub fn download(req: &mut Request) -> CargoResult<Response> {
     }
 }
 
+/// Handles the `GET /crates/:crate_id/downloads` route.
 pub fn downloads(req: &mut Request) -> CargoResult<Response> {
     let crate_name = &req.params()["crate_id"];
     let tx = try!(req.tx());
@@ -931,6 +937,7 @@ fn user_and_crate(req: &mut Request) -> CargoResult<(User, Crate)> {
     Ok((user.clone(), krate))
 }
 
+/// Handles the `PUT /crates/:crate_id/follow` route.
 pub fn follow(req: &mut Request) -> CargoResult<Response> {
     let (user, krate) = try!(user_and_crate(req));
     let tx = try!(req.tx());
@@ -946,6 +953,7 @@ pub fn follow(req: &mut Request) -> CargoResult<Response> {
     Ok(req.json(&R { ok: true }))
 }
 
+/// Handles the `DELETE /crates/:crate_id/follow` route.
 pub fn unfollow(req: &mut Request) -> CargoResult<Response> {
     let (user, krate) = try!(user_and_crate(req));
     let tx = try!(req.tx());
@@ -957,6 +965,7 @@ pub fn unfollow(req: &mut Request) -> CargoResult<Response> {
     Ok(req.json(&R { ok: true }))
 }
 
+/// Handles the `GET /crates/:crate_id/following` route.
 pub fn following(req: &mut Request) -> CargoResult<Response> {
     let (user, krate) = try!(user_and_crate(req));
     let tx = try!(req.tx());
@@ -968,6 +977,7 @@ pub fn following(req: &mut Request) -> CargoResult<Response> {
     Ok(req.json(&R { following: rows.next().is_some() }))
 }
 
+/// Handles the `GET /crates/:crate_id/versions` route.
 pub fn versions(req: &mut Request) -> CargoResult<Response> {
     let crate_name = &req.params()["crate_id"];
     let tx = try!(req.tx());
@@ -981,6 +991,7 @@ pub fn versions(req: &mut Request) -> CargoResult<Response> {
     Ok(req.json(&R{ versions: versions }))
 }
 
+/// Handles the `GET /crates/:crate_id/owners` route.
 pub fn owners(req: &mut Request) -> CargoResult<Response> {
     let crate_name = &req.params()["crate_id"];
     let tx = try!(req.tx());
@@ -993,10 +1004,12 @@ pub fn owners(req: &mut Request) -> CargoResult<Response> {
     Ok(req.json(&R{ users: owners }))
 }
 
+/// Handles the `PUT /crates/:crate_id/owners` route.
 pub fn add_owners(req: &mut Request) -> CargoResult<Response> {
     modify_owners(req, true)
 }
 
+/// Handles the `DELETE /crates/:crate_id/owners` route.
 pub fn remove_owners(req: &mut Request) -> CargoResult<Response> {
     modify_owners(req, false)
 }
@@ -1054,6 +1067,7 @@ fn modify_owners(req: &mut Request, add: bool) -> CargoResult<Response> {
     Ok(req.json(&R{ ok: true }))
 }
 
+/// Handles the `GET /crates/:crate_id/reverse_dependencies` route.
 pub fn reverse_dependencies(req: &mut Request) -> CargoResult<Response> {
     let name = &req.params()["crate_id"];
     let conn = try!(req.tx());

src/user/mod.rs

@@ -136,7 +136,9 @@ impl Model for User {
     fn table_name(_: Option<User>) -> &'static str { "users" }
 }
 
+/// Handles the `GET /authorize_url` route.
 pub fn github_authorize(req: &mut Request) -> CargoResult<Response> {
+    // Generate a random 16 char ASCII string
     let state: String = thread_rng().gen_ascii_chars().take(16).collect();
     req.session().insert("github_oauth_state".to_string(), state.clone());
 
@@ -147,6 +149,7 @@ pub fn github_authorize(req: &mut Request) -> CargoResult<Response> {
     Ok(req.json(&R { url: url.to_string(), state: state }))
 }
 
+/// Handles the `GET /authorize` route.
 pub fn github_access_token(req: &mut Request) -> CargoResult<Response> {
     // Parse the url query
     let mut query = req.query();
@@ -197,11 +200,13 @@ pub fn github_access_token(req: &mut Request) -> CargoResult<Response> {
     me(req)
 }
 
+/// Handles the `GET /logout` route.
 pub fn logout(req: &mut Request) -> CargoResult<Response> {
     req.session().remove(&"user_id".to_string());
     Ok(req.json(&true))
 }
 
+/// Handles the `GET /me/reset_token` route.
 pub fn reset_token(req: &mut Request) -> CargoResult<Response> {
     let user = try!(req.user());
 
@@ -215,6 +220,7 @@ pub fn reset_token(req: &mut Request) -> CargoResult<Response> {
     Ok(req.json(&R { api_token: token }))
 }
 
+/// Handles the `GET /me` route.
 pub fn me(req: &mut Request) -> CargoResult<Response> {
     let user = try!(req.user());
 
@@ -224,6 +230,7 @@ pub fn me(req: &mut Request) -> CargoResult<Response> {
     Ok(req.json(&R{ user: user.clone().encodable(), api_token: token }))
 }
 
+/// Handles the `GET /me/updates` route.
 pub fn updates(req: &mut Request) -> CargoResult<Response> {
     let user = try!(req.user());
     let (offset, limit) = try!(req.pagination(10, 100));

src/version.rs

@@ -210,6 +210,7 @@ impl Model for Version {
     fn table_name(_: Option<Version>) -> &'static str { "versions" }
 }
 
+/// Handles the `GET /versions` route.
 pub fn index(req: &mut Request) -> CargoResult<Response> {
     let conn = try!(req.tx());
 
@@ -247,6 +248,7 @@ pub fn index(req: &mut Request) -> CargoResult<Response> {
     Ok(req.json(&R { versions: versions }))
 }
 
+/// Handles the `GET /versions/:version_id` route.
 pub fn show(req: &mut Request) -> CargoResult<Response> {
     let (version, krate) = match req.params().find("crate_id") {
         Some(..) => try!(version_and_crate(req)),
@@ -281,6 +283,7 @@ fn version_and_crate(req: &mut Request) -> CargoResult<(Version, Crate)> {
     Ok((version, krate))
 }
 
+/// Handles the `GET /crates/:crate_id/:version/dependencies` route.
 pub fn dependencies(req: &mut Request) -> CargoResult<Response> {
     let (version, _) = try!(version_and_crate(req));
     let tx = try!(req.tx());
@@ -294,6 +297,7 @@ pub fn dependencies(req: &mut Request) -> CargoResult<Response> {
     Ok(req.json(&R{ dependencies: deps }))
 }
 
+/// Handles the `GET /crates/:crate_id/:version/downloads` route.
 pub fn downloads(req: &mut Request) -> CargoResult<Response> {
     let (version, _) = try!(version_and_crate(req));
 
@@ -313,6 +317,7 @@ pub fn downloads(req: &mut Request) -> CargoResult<Response> {
     Ok(req.json(&R{ version_downloads: downloads }))
 }
 
+/// Handles the `GET /crates/:crate_id/:version/authors` route.
 pub fn authors(req: &mut Request) -> CargoResult<Response> {
     let (version, _) = try!(version_and_crate(req));
     let tx = try!(req.tx());
@@ -331,10 +336,12 @@ pub fn authors(req: &mut Request) -> CargoResult<Response> {
     Ok(req.json(&R{ users: users, meta: Meta { names: names } }))
 }
 
+/// Handles the `DELETE /crates/:crate_id/:version/yank` route.
 pub fn yank(req: &mut Request) -> CargoResult<Response> {
     modify_yank(req, true)
 }
 
+/// Handles the `PUT /crates/:crate_id/:version/unyank` route.
 pub fn unyank(req: &mut Request) -> CargoResult<Response> {
     modify_yank(req, false)
 }