From 8e5ac6f2d4e52eea95e5a6fc2905ce511ac4956e Mon Sep 17 00:00:00 2001
From: Teddy Wing
Date: Sun, 2 Aug 2020 18:49:36 +0200
Subject: Add documentation comments

Light documentation for our various functions and types.
---
 src/arg.rs        |  1 +
 src/config.rs     | 18 ++++++++++++++++++
 src/error.rs      |  1 +
 src/owner_repo.rs |  9 +++++++++
 src/suggestion.rs |  2 ++
 5 files changed, 31 insertions(+)

(limited to 'src')

diff --git a/src/arg.rs b/src/arg.rs
index eaea67b..d1d62d9 100644
--- a/src/arg.rs
+++ b/src/arg.rs
@@ -1,6 +1,7 @@
 use regex::{self, Regex};
 
 
+/// Check if `s` is a numeric ID.
 pub fn is_suggestion_id(s: &str) -> Result<bool, regex::Error> {
     let re = Regex::new(r"^\d+$")?;
 
diff --git a/src/config.rs b/src/config.rs
index e605439..39a8158 100644
--- a/src/config.rs
+++ b/src/config.rs
@@ -8,8 +8,10 @@ use thiserror::Error;
 use crate::owner_repo::{self, OwnerRepo};
 
 
+/// Program-specific prefix for Git config values.
 const GIT_CONFIG_PREFIX: &'static str = "githubSuggestion.";
 
+/// Configuration errors.
 #[derive(Debug, Error)]
 pub enum Error {
     #[error("Unable to parse arguments: {0}")]
@@ -28,6 +30,7 @@ pub enum Error {
     Git(#[from] git2::Error),
 }
 
+/// Configuration extracted from config files and command line arguments.
 pub struct Config {
     pub github_token: String,
     pub o_r: Result<OwnerRepo, owner_repo::Error>,
@@ -35,6 +38,8 @@ pub struct Config {
 }
 
 impl Config {
+    /// Set up command line arguments. Extract configuration values from command
+    /// line arguments, Git config, and environment variables.
     pub fn get(args: &[String], usage_brief: &str) -> Result<Self, Error> {
         let mut opts = Options::new();
 
@@ -79,6 +84,11 @@ impl Config {
         })
     }
 
+    /// Get a GitHub token, checking the following places in order:
+    ///
+    /// 1. Command line argument
+    /// 2. Git config
+    /// 3. Environment variable
     fn github_token(
         opt_matches: &getopts::Matches,
         git_config: &git2::Config,
@@ -101,6 +111,12 @@ impl Config {
         }
     }
 
+    /// Get the Git remote name from the following places in order:
+    ///
+    /// 1. Command line argument
+    /// 2. Git config
+    ///
+    /// If the value wasn't set, return `Ok(None)`.
     fn remote(
         opt_matches: &getopts::Matches,
         git_config: &git2::Config,
@@ -115,10 +131,12 @@ impl Config {
     }
 }
 
+/// Print command line usage information to standard output.
 fn print_usage(opts: &Options, brief: &str) {
     print!("{}", opts.usage(brief));
 }
 
+/// Build a Git config key using the program-specific prefix and a subkey.
 fn git_config_key(key: &str) -> String {
     format!("{}.{}", GIT_CONFIG_PREFIX, key)
 }
diff --git a/src/error.rs b/src/error.rs
index bcca3e1..6b369f0 100644
--- a/src/error.rs
+++ b/src/error.rs
@@ -9,6 +9,7 @@ pub enum Error {
 }
 
 
+/// Print to standard error with a program-specific prefix.
 #[macro_export]
 macro_rules! gseprintln {
     ($arg:expr) => ({
diff --git a/src/owner_repo.rs b/src/owner_repo.rs
index a94c67f..6098ff0 100644
--- a/src/owner_repo.rs
+++ b/src/owner_repo.rs
@@ -6,6 +6,7 @@ use url;
 use url::Url;
 
 
+/// Errors getting an `OwnerRepo` from a remote in a Git repository.
 #[derive(Debug, Error)]
 pub enum Error {
     #[error(transparent)]
@@ -18,6 +19,7 @@ pub enum Error {
     NoRemote(String),
 }
 
+/// Errors parsing an `OwnerRepo`.
 #[derive(Debug, Error)]
 pub enum OwnerRepoError {
     #[error("Unable to parse URL")]
@@ -37,6 +39,9 @@ pub struct OwnerRepo {
     pub repo: String,
 }
 
+/// Parse an owner-repo pair from a Git remote. Can be either an HTTP URL
+/// (`https://github.com/teddywing/github-suggestion.git`) or an SSH-style
+/// reference (`git@github.com:teddywing/github-suggestion.git`).
 impl FromStr for OwnerRepo {
     type Err = OwnerRepoError;
 
@@ -63,6 +68,8 @@ impl FromStr for OwnerRepo {
 }
 
 impl OwnerRepo {
+    /// Parse an `OwnerRepo` from the URL for `remote_name` in the current
+    /// repository.
     pub fn from_remote(
         remote_name: Option<&str>,
     ) -> Result<OwnerRepo, Error> {
@@ -80,6 +87,8 @@ impl OwnerRepo {
         Ok(url.parse()?)
     }
 
+    /// Parse an `OwnerRepo` from an SSH-style reference
+    /// (`git@github.com:teddywing/github-suggestion.git`).
     pub fn from_ssh(ssh: &str) -> Result<Self, OwnerRepoError> {
         let address_path: Vec<_> = ssh.splitn(2, ':').collect();
         let path = address_path.get(1)
diff --git a/src/suggestion.rs b/src/suggestion.rs
index fc22a7c..9f23a0d 100644
--- a/src/suggestion.rs
+++ b/src/suggestion.rs
@@ -9,6 +9,8 @@ use crate::arg::is_suggestion_id;
 use crate::config::Config;
 
 
+/// For all suggestions in `config.suggestions`, fetch the suggestion from the
+/// API and call `f` with it.
 pub fn for_suggestion<F>(config: &Config, f: F)
 where F: Fn(&Suggestion)
 {
-- 
cgit v1.2.3