Merge pull request #1087 from code-corps/code-and-comment-cleanups-fo…

…r-issue

Code and comment cleanups for Issues

lib/code_corps/github/event/issues/issue_linker.ex

@@ -1,43 +1,43 @@
 defmodule CodeCorps.GitHub.Event.Issues.IssueLinker do
   @moduledoc ~S"""
-  In charge of finding a issue to link with a Task when processing an Issues
-  webhook.
+  In charge of finding a `CodeCorps.GithubIssue` to link with a
+  `CodeCorps.Issue` when processing an Issues webhook, or handling a
+  `CodeCorpsWeb.TaskController` request.
 
   The only entry point is `create_or_update_issue/1`.
   """
 
   alias CodeCorps.{
+    GitHub.Adapters,
     GithubIssue,
     GithubRepo,
     Repo
   }
 
-  alias CodeCorps.GitHub.Adapters.Issue, as: IssueAdapter
-
-  @typep linking_result :: {:ok, GithubIssue.t} |
-                           {:error, Ecto.Changeset.t}
+  @typep linking_result :: {:ok, GithubIssue.t} | {:error, Ecto.Changeset.t}
 
   @doc ~S"""
-  Finds or creates a `GithubIssue` using the data in a GitHub Issue payload.
+  Finds or creates a `CodeCorps.GithubIssue` using the data in a GitHub Issue
+  payload.
 
   The process is as follows:
-
   - Search for the issue in our database with the payload data.
-    - If we return a single `GithubIssue`, then the `GithubIssue` should be
-      updated.
-    - If there are no matching `GithubIssue` records, then a `GithubIssue`
-      should be created.
+   - If found, update it with payload data
+   - If not found, create it from payload data
+
+  `CodeCorps.GitHub.AdaptersIssue.to_issue/1` is used to adapt the payload data.
   """
   @spec create_or_update_issue(GithubRepo.t, map) :: linking_result
   def create_or_update_issue(%GithubRepo{} = github_repo, %{"id" => github_issue_id} = attrs) do
-    params = IssueAdapter.to_issue(attrs)
+    params = Adapters.Issue.to_issue(attrs)
 
     case Repo.get_by(GithubIssue, github_id: github_issue_id) do
       nil -> create_issue(github_repo, params)
       %GithubIssue{} = issue -> update_issue(issue, params)
     end
   end
 
+  @spec create_issue(GithubRepo.t, map) :: linking_result
   defp create_issue(%GithubRepo{id: github_repo_id}, params) do
     params = Map.put(params, :github_repo_id, github_repo_id)
 
@@ -46,6 +46,7 @@ defmodule CodeCorps.GitHub.Event.Issues.IssueLinker do
     |> Repo.insert
   end
 
+  @spec update_issue(GithubIssue.t, map) :: linking_result
   defp update_issue(%GithubIssue{} = github_issue, params) do
     github_issue
     |> GithubIssue.update_changeset(params)