Add documentation comments

Light documentation for our various functions and types.

3 files changed, 14 insertions, 0 deletions

diff --git a/github-suggestion/src/client.rs b/github-suggestion/src/client.rs
index c6ae1f1..eb81fbc 100644
--- a/github-suggestion/src/client.rs
+++ b/github-suggestion/src/client.rs
@@ -5,6 +5,7 @@ use thiserror::Error;
 use crate::suggestion::Suggestion;
 
 
+/// Client and network errors.
 #[derive(Debug, Error)]
 pub enum Error {
     #[error("GitHub client error: {0}")]
@@ -15,6 +16,7 @@ pub enum Error {
 }
 
 
+/// A GitHub client wrapper for a specific repository.
 pub struct Client<'a> {
     client: Github,
     owner: &'a str,
@@ -22,6 +24,7 @@ pub struct Client<'a> {
 }
 
 impl<'a> Client<'a> {
+    /// Create a new GitHub client.
     pub fn new(
         token: &str,
         owner: &'a str, repo: &'a str,
@@ -34,6 +37,7 @@ impl<'a> Client<'a> {
         Ok(Client { client, owner, repo })
     }
 
+    /// Fetch a suggestion comment from GitHub by its ID.
     pub fn fetch(&self, id: &str) -> Result<Suggestion, Error> {
         let response = self.client
             .get()
diff --git a/github-suggestion/src/suggestion.rs b/github-suggestion/src/suggestion.rs
index 2c92e6a..48fcb0c 100644
--- a/github-suggestion/src/suggestion.rs
+++ b/github-suggestion/src/suggestion.rs
@@ -40,6 +40,7 @@ enum LineEnding {
     CrLf,
 }
 
+/// A suggestion comment extracted from the GitHub API.
 #[derive(Debug, Deserialize)]
 pub struct Suggestion {
     #[serde(rename = "diff_hunk")]
@@ -60,12 +61,14 @@ pub struct Suggestion {
 }
 
 impl Suggestion {
+    /// Get the suggestion diff for the current repository.
     pub fn diff(&self) -> Result<String, Error> {
         let repo = Repository::open(".")?;
 
         self.diff_with_repo(&repo)
     }
 
+    /// Get the suggestion diff for `repo`.
     fn diff_with_repo(&self, repo: &Repository) -> Result<String, Error> {
         let commit = repo.find_commit(self.commit.parse()?)?;
 
@@ -104,6 +107,7 @@ impl Suggestion {
         )
     }
 
+    /// Extract suggestion code from a comment body.
     fn suggestion_with_line_ending(
         &self,
         line_ending: &LineEnding,
@@ -120,6 +124,7 @@ impl Suggestion {
         Ok(s)
     }
 
+    /// Apply the suggestion to the current repository.
     pub fn apply(&self) -> Result<(), Error> {
         let repo = Repository::open(".")?;
 
@@ -135,6 +140,7 @@ impl Suggestion {
         Ok(())
     }
 
+    /// Apply the patch in `reader` to `writer`.
     fn apply_to<R: BufRead, W: Write>(
         &self,
         reader: R,
diff --git a/github-suggestion/src/url.rs b/github-suggestion/src/url.rs
index 60a3d0e..48da7d2 100644
--- a/github-suggestion/src/url.rs
+++ b/github-suggestion/src/url.rs
@@ -6,6 +6,7 @@ use url;
 use url::Url;
 
 
+/// Errors parsing a suggestion URL.
 #[derive(Debug, Error)]
 pub enum Error {
     #[error("Unable to parse URL")]
@@ -21,6 +22,7 @@ pub enum Error {
     NoOwnerRepo,
 }
 
+/// The important parts of a suggestion comment URL.
 #[derive(Debug)]
 pub struct SuggestionUrl {
     pub owner: String,
@@ -28,6 +30,8 @@ pub struct SuggestionUrl {
     pub comment_id: String,
 }
 
+/// Parses a URL with the format
+/// `https://github.com/teddywing/github-suggestion/pull/1#discussion_r459691747`.
 impl FromStr for SuggestionUrl {
     type Err = Error;