Add docstrings to pre-existing public API elements (#77)

PR #72 (gist API) added docstrings to all new public types and methods,
leaving the pre-existing API undocumented. This adds docstrings to all
pre-existing public classes, primitives, actors, and their public methods
to bring the entire library to a consistent documentation standard.

Also replaces the placeholder package docstring with a proper overview
that guides users to the GitHub entry point and explains the
Promise-based return pattern.

The request/ subpackage is excluded — it's intended to be extracted
to its own library and will be documented separately.

Closes #74

Author: SeanTAllen

github_rest_api/asset.pony

@@ -2,6 +2,10 @@ use "json"
 use req = "request"
 
 class val Asset
+  """
+  A file attached to a GitHub release. Contains the asset's metadata including
+  its name, size, download count, and the browser download URL.
+  """
   let _creds: req.Credentials
 
   let id: I64
@@ -50,6 +54,9 @@ class val Asset
     browser_download_url = browser_download_url'
 
 primitive AssetJsonConverter is req.JsonConverter[Asset]
+  """
+  Converts a JSON object into an Asset.
+  """
   fun apply(json: JsonNav, creds: req.Credentials): Asset ? =>
     let id = json("id").as_i64()?
     let node_id = json("node_id").as_string()?

github_rest_api/commit.pony

@@ -6,6 +6,10 @@ use ut = "uri/template"
 type CommitOrError is (Commit | req.RequestError)
 
 class val Commit
+  """
+  A GitHub commit, containing its SHA, changed files, and nested git commit
+  data (author, committer, message).
+  """
   let _creds: req.Credentials
   let sha: String
   let files: Array[CommitFile] val
@@ -31,6 +35,9 @@ class val Commit
     comments_url = comments_url'
 
 primitive GetCommit
+  """
+  Fetches a single commit by owner, repo, and SHA.
+  """
   fun apply(owner: String,
     repo: String,
     sha: String,
@@ -65,6 +72,9 @@ primitive GetCommit
     p
 
 primitive CommitJsonConverter is req.JsonConverter[Commit]
+  """
+  Converts a JSON object from the commits API into a Commit.
+  """
   fun apply(json: JsonNav, creds: req.Credentials): Commit ? =>
     let sha = json("sha").as_string()?
 

github_rest_api/commit_file.pony

@@ -3,6 +3,9 @@ use "promises"
 use req = "request"
 
 class val CommitFile
+  """
+  A file changed in a commit, with its SHA, modification status, and filename.
+  """
   let _creds: req.Credentials
   let sha: String
   let status: String
@@ -19,6 +22,9 @@ class val CommitFile
     filename = filename'
 
 primitive CommitFileJsonConverter is req.JsonConverter[CommitFile]
+  """
+  Converts a JSON object into a CommitFile.
+  """
   fun apply(json: JsonNav,
     creds: req.Credentials): CommitFile ?
   =>

github_rest_api/git_commit.pony

@@ -2,6 +2,11 @@ use "json"
 use req = "request"
 
 class val GitCommit
+  """
+  The git commit data within a GitHub commit, containing author, committer,
+  message, and the git-level URL. This is the nested `commit` object inside the
+  top-level Commit response.
+  """
   let _creds: req.Credentials
   let author: GitPerson
   let committer: GitPerson
@@ -21,6 +26,9 @@ class val GitCommit
     url = url'
 
 primitive GitCommitJsonConverter is req.JsonConverter[GitCommit]
+  """
+  Converts a JSON object into a GitCommit.
+  """
   fun apply(json: JsonNav, creds: req.Credentials): GitCommit ? =>
     let author = GitPersonJsonConverter(json("author"), creds)?
     let committer = GitPersonJsonConverter(json("committer"), creds)?

github_rest_api/git_person.pony

@@ -2,6 +2,9 @@ use "json"
 use req = "request"
 
 class val GitPerson
+  """
+  A git author or committer identity with a name and email address.
+  """
   let name: String
   let email: String
 
@@ -10,6 +13,9 @@ class val GitPerson
     email = email'
 
 primitive GitPersonJsonConverter is req.JsonConverter[GitPerson]
+  """
+  Converts a JSON object into a GitPerson.
+  """
   fun apply(json: JsonNav, creds: req.Credentials): GitPerson ? =>
     let name = json("name").as_string()?
     let email = json("email").as_string()?

github_rest_api/github.pony

@@ -5,6 +5,12 @@ use req = "request"
 type RepositoryOrError is (Repository | req.RequestError)
 
 class val GitHub
+  """
+  Entry point for all GitHub REST API operations. Holds credentials and
+  authentication context used to issue requests. Each method corresponds to a
+  top-level API operation; returned models provide convenience methods for
+  further related calls.
+  """
   let _creds: req.Credentials
 
   new val create(creds: req.Credentials) =>

github_rest_api/github_rest_api.pony

@@ -1,3 +1,20 @@
 """
-Package documentation goes here
+A Pony library for interacting with the GitHub REST API.
+
+Start by creating a `GitHub` instance with your credentials, then use its
+methods to fetch repositories, issues, gists, and other resources. All API
+operations return `Promise`-based results as `(Model | RequestError)` unions.
+
+```pony
+use "github_rest_api"
+use "github_rest_api/request"
+
+let creds = Credentials(auth, "your-token-here")
+let github = GitHub(creds)
+github.get_repo("ponylang", "ponyc")
+```
+
+Returned model objects provide convenience methods for related API calls —
+for example, a `Repository` can create labels and releases, and an `Issue`
+can create comments.
 """

github_rest_api/issue.pony

@@ -6,6 +6,11 @@ use ut = "uri/template"
 type IssueOrError is (Issue | req.RequestError)
 
 class val Issue
+  """
+  A GitHub issue. Provides convenience methods to create comments and list
+  existing comments on this issue. The `pull_request` field is present when the
+  issue is actually a pull request.
+  """
   let _creds: req.Credentials
 
   let number: I64
@@ -55,12 +60,21 @@ class val Issue
     pull_request = pull_request'
 
   fun create_comment(comment: String): Promise[IssueCommentOrError] =>
+    """
+    Creates a new comment on this issue.
+    """
     CreateIssueComment.by_url(comments_url, comment, _creds)
 
   fun get_comments(): Promise[IssueCommentsOrError] =>
+    """
+    Fetches all comments on this issue.
+    """
     GetIssueComments.by_url(comments_url, _creds)
 
 primitive GetIssue
+  """
+  Fetches a single issue by owner, repo, and number.
+  """
   fun apply(owner: String,
     repo: String,
     number: I64,
@@ -95,6 +109,10 @@ primitive GetIssue
     p
 
 primitive GetRepositoryIssues
+  """
+  Lists issues in a repository as a paginated list, optionally filtered by
+  labels and state.
+  """
   fun apply(owner: String,
     repo: String,
     creds: req.Credentials,
@@ -141,6 +159,9 @@ primitive GetRepositoryIssues
 
 
 primitive IssueJsonConverter is req.JsonConverter[Issue]
+  """
+  Converts a JSON object from the issues API into an Issue.
+  """
   fun apply(json: JsonNav, creds: req.Credentials): Issue ? =>
     let url = json("url").as_string()?
     let respository_url = json("repository_url").as_string()?

github_rest_api/issue_comment.pony

@@ -9,6 +9,9 @@ type IssueComments is Array[IssueComment] val
 type IssueCommentsOrError is (IssueComments | req.RequestError)
 
 class val IssueComment
+  """
+  A comment on a GitHub issue.
+  """
   let _creds: req.Credentials
   let body: String
   let url: String
@@ -28,6 +31,9 @@ class val IssueComment
     issue_url = issue_url'
 
 primitive CreateIssueComment
+  """
+  Creates a new comment on an issue.
+  """
   fun apply(owner: String,
     repo: String,
     number: I64,
@@ -68,6 +74,9 @@ primitive CreateIssueComment
     p
 
 primitive GetIssueComments
+  """
+  Fetches all comments on an issue.
+  """
   fun apply(owner: String,
     repo: String,
     number: I64,
@@ -102,6 +111,10 @@ primitive GetIssueComments
     p
 
 primitive IssueCommentsURL
+  """
+  Builds the URL for an issue's comments endpoint from owner, repo, and issue
+  number.
+  """
   fun apply(owner: String, repo: String, number: I64)
     : (String | ut.URITemplateParseError)
   =>
@@ -118,6 +131,9 @@ primitive IssueCommentsURL
     end
 
 primitive IssueCommentJsonConverter is req.JsonConverter[IssueComment]
+  """
+  Converts a JSON object into an IssueComment.
+  """
   fun apply(json: JsonNav,
     creds: req.Credentials): IssueComment ?
   =>
@@ -129,6 +145,9 @@ primitive IssueCommentJsonConverter is req.JsonConverter[IssueComment]
     IssueComment(creds, body, url, html_url, issue_url)
 
 primitive IssueCommentsJsonConverter is req.JsonConverter[Array[IssueComment] val]
+  """
+  Converts a JSON array of issue comment objects into an Array of IssueComment.
+  """
   fun apply(json: JsonNav,
     creds: req.Credentials): Array[IssueComment] val ?
   =>

github_rest_api/issue_pull_request.pony

@@ -29,6 +29,9 @@ class val IssuePullRequest
     merged_at = merged_at'
 
 primitive IssuePullRequestJsonConverter is req.JsonConverter[IssuePullRequest]
+  """
+  Converts a JSON object into an IssuePullRequest.
+  """
   fun apply(json: JsonNav, creds: req.Credentials): IssuePullRequest ? =>
     let url = json("url").as_string()?
     let html_url = json("html_url").as_string()?