Merge pull request #215 from Turbo87/doc

Documentation

Author: alexcrichton

src/app.rs

@@ -12,17 +12,25 @@ use curl::http;
 
 use {db, Config};
 
+/// The `App` struct holds the main components of the application like
+/// the database connection pool and configurations
 pub struct App {
+    /// The database connection pool
     pub database: db::Pool,
+
+    /// The GitHub OAuth2 configuration
     pub github: oauth2::Config,
     pub bucket: s3::Bucket,
     pub s3_proxy: Option<String>,
     pub session_key: String,
     pub git_repo: Mutex<git2::Repository>,
     pub git_repo_checkout: PathBuf,
+
+    /// The server configuration
     pub config: Config,
 }
 
+/// The `AppMiddleware` injects an `App` instance into the `Request` extensions
 pub struct AppMiddleware {
     app: Arc<App>
 }
@@ -82,6 +90,7 @@ impl Middleware for AppMiddleware {
     }
 }
 
+/// Adds an `app()` method to the `Request` type returning the global `App` instance
 pub trait RequestApp {
     fn app(&self) -> &Arc<App>;
 }

src/bin/delete-crate.rs

@@ -18,6 +18,7 @@ use std::io::prelude::*;
 
 use cargo_registry::Crate;
 
+#[allow(dead_code)]
 fn main() {
     let conn = postgres::Connection::connect(&env("DATABASE_URL")[..],
                                              &postgres::SslMode::None).unwrap();
@@ -97,4 +98,3 @@ fn delete(tx: &postgres::Transaction) {
     io::stdin().read_line(&mut line).unwrap();
     if !line.starts_with("y") { panic!("aborting transaction"); }
 }
-

src/bin/delete-version.rs

@@ -18,6 +18,7 @@ use std::io::prelude::*;
 
 use cargo_registry::{Crate, Version};
 
+#[allow(dead_code)]
 fn main() {
     let conn = postgres::Connection::connect(&env("DATABASE_URL")[..],
                                              &postgres::SslMode::None).unwrap();
@@ -75,4 +76,3 @@ fn delete(tx: &postgres::Transaction) {
     io::stdin().read_line(&mut line).unwrap();
     if !line.starts_with("y") { panic!("aborting transaction"); }
 }
-

src/bin/migrate.rs

@@ -12,6 +12,7 @@ use migrate::Migration;
 use cargo_registry::krate::Crate;
 use cargo_registry::model::Model;
 
+#[allow(dead_code)]
 fn main() {
     let conn = postgres::Connection::connect(&env("DATABASE_URL")[..],
                                              &postgres::SslMode::None).unwrap();

src/bin/populate.rs

@@ -15,6 +15,7 @@ use std::env;
 use time::Duration;
 use rand::{StdRng, Rng};
 
+#[allow(dead_code)]
 fn main() {
     let conn = postgres::Connection::connect(&env("DATABASE_URL")[..],
                                              &postgres::SslMode::None).unwrap();

src/bin/server.rs

@@ -13,6 +13,7 @@ use std::path::PathBuf;
 use std::sync::Arc;
 use std::sync::mpsc::channel;
 
+#[allow(dead_code)]
 fn main() {
     env_logger::init().unwrap();
     let url = env("GIT_REPO_URL");

src/user/middleware.rs

@@ -13,18 +13,30 @@ pub struct Middleware;
 
 impl conduit_middleware::Middleware for Middleware {
     fn before(&self, req: &mut Request) -> Result<(), Box<Error+Send>> {
+        // Check if the request has a session cookie with a `user_id` property inside
         let id = { req.session().get("user_id").and_then(|s| s.parse().ok()) };
+
         let user = match id {
+
+            // `user_id` was found on the session
             Some(id) => {
+
+                // Look for a user in the database with the given `user_id`
                 match User::find(try!(req.tx().map_err(std_error)), id) {
                     Ok(user) => user,
                     Err(..) => return Ok(()),
                 }
             }
+
+            // `user_id` was *not* found on the session
             None => {
+
+                // Look for an `Authorization` header on the request
                 let tx = try!(req.tx().map_err(std_error));
                 match req.headers().find("Authorization") {
                     Some(headers) => {
+
+                        // Look for a user in the database with a matching API token
                         match User::find_by_api_token(tx, &headers[0]) {
                             Ok(user) => user,
                             Err(..) => return Ok(())
@@ -35,6 +47,7 @@ impl conduit_middleware::Middleware for Middleware {
             }
         };
 
+        // Attach the `User` model from the database to the request
         req.mut_extensions().insert(user);
         Ok(())
     }

src/user/mod.rs

@@ -20,6 +20,7 @@ pub use self::middleware::{Middleware, RequestUser};
 
 pub mod middleware;
 
+/// The model representing a row in the `users` database table.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct User {
     pub id: i32,
@@ -31,6 +32,7 @@ pub struct User {
     pub api_token: String,
 }
 
+/// The serialization format for the `User` model.
 #[derive(RustcDecodable, RustcEncodable)]
 pub struct EncodableUser {
     pub id: i32,
@@ -41,6 +43,7 @@ pub struct EncodableUser {
 }
 
 impl User {
+    /// Queries the database for a user with a certain `gh_login` value.
     pub fn find_by_login(conn: &GenericConnection,
                          login: &str) -> CargoResult<User> {
         let stmt = try!(conn.prepare("SELECT * FROM users
@@ -52,6 +55,7 @@ impl User {
         Ok(Model::from_row(&row))
     }
 
+    /// Queries the database for a user with a certain `api_token` value.
     pub fn find_by_api_token(conn: &GenericConnection,
                              token: &str) -> CargoResult<User> {
         let stmt = try!(conn.prepare("SELECT * FROM users \
@@ -62,6 +66,7 @@ impl User {
         })
     }
 
+    /// Updates a user or inserts a new user into the database.
     pub fn find_or_insert(conn: &GenericConnection,
                           login: &str,
                           email: Option<&str>,
@@ -102,10 +107,12 @@ impl User {
         }))))
     }
 
+    /// Generates a new crates.io API token.
     pub fn new_api_token() -> String {
         thread_rng().gen_ascii_chars().take(32).collect()
     }
 
+    /// Converts this `User` model into an `EncodableUser` for JSON serialization.
     pub fn encodable(self) -> EncodableUser {
         let User { id, email, api_token: _, gh_access_token: _,
                    name, gh_login, avatar } = self;