docs(backend): Document some functions and structures

Signed-off-by: Lucien Cartier-Tilet <lucien@phundrak.com>

src/data.rs

@@ -6,6 +6,9 @@ pub struct Data {
     pub user: User,
 }
 
+/// GitHub user
+///
+/// Contains their newest, most starred, and pinned repositories,
 #[derive(Default, Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct User {
@@ -14,24 +17,31 @@ pub struct User {
     pub pinned: Pinned,
 }
 
+/// Newest repositories
 #[derive(Default, Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct Newest {
     pub nodes: Vec<Repository>,
 }
 
+/// Most starred repositories
 #[derive(Default, Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct MostStarred {
     pub nodes: Vec<Repository>,
 }
 
+/// Pinned repositories
 #[derive(Default, Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct Pinned {
     pub nodes: Vec<Repository>,
 }
 
+/// Repository
+///
+/// Contains the name of the repository, the amount of stars, and the
+/// amount of forks of the repository
 #[derive(Default, Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase", rename = "node")]
 pub struct Repository {

src/main.rs

@@ -7,6 +7,11 @@ use std::collections::HashMap;
 
 mod data;
 
+/// Squeleton of the GitHub GraphQL query
+///
+/// This is a macro and not a constant because `format!()` does not
+/// accept anything besides string litterals as its first argument.
+/// Fortunately, macros "return" string litterals, so this should do.
 macro_rules! GITHUB_GRAPHQL_QUERY {
     () => {
         r#"query {{
@@ -59,11 +64,13 @@ impl Default for AppState {
 
 impl error::ResponseError for MyError {}
 
+/// Retrieve the GitHub token from the environment variables.
 fn github_token() -> String {
     std::env::var("GH_TOKEN")
         .expect("Environment variable GH_TOKEN **MUST** be set!")
 }
 
+/// Prepare headers for querying GitHub’s API
 fn prepare_github_query_headers(gh_token: &String) -> HashMap<String, String> {
     let mut headers: HashMap<String, String> = HashMap::new();
     headers.insert("Authorization".to_string(), format!("Bearer {}", gh_token));
@@ -71,11 +78,21 @@ fn prepare_github_query_headers(gh_token: &String) -> HashMap<String, String> {
     headers
 }
 
+/// Create a GraphQL client for GitHub’s API
 fn make_gh_graphql_client(gh_token: &String) -> Client {
     let headers = prepare_github_query_headers(gh_token);
     Client::new_with_headers("https://api.github.com/graphql", headers)
 }
 
+/// Make GraphQL call to GitHub
+///
+/// This function should be called only when the Redis database holds
+/// either no records or outdated records.
+///
+/// # Returns
+///
+/// Returns the Json response from GitHub. This should be parsable by
+/// serde into the `Data` type.
 async fn make_gh_graphql_call(
     user: String,
     gh_token: &String,
@@ -102,6 +119,7 @@ async fn user_info_github(
     }
 }
 
+/// Setup various helpers for application
 fn setup_application() {
     std::env::set_var("RUST_LOG", "debug");
     env_logger::init();