Explanations

Author: begedin

lib/code_corps/github/api/eager_api.ex

@@ -42,11 +42,39 @@ defmodule CodeCorps.GitHub.EagerAPI do
     end
   end
 
-  def extract_total_pages(links_string) do
+  defp extract_total_pages(links_string) do
+    # Unfortunately, the paginating info we get from GitHub's responses is not
+    # suitable for easy extraction.
+    #
+    # The information is stored in the following response header:
+    #
+    # ```
+    # {"Link", '<https://api.github.com/search/code?q=addClass+user%3Amozilla&page=15>; rel="next",
+    #           <https://api.github.com/search/code?q=addClass+user%3Amozilla&page=34>; rel="last",
+    #           <https://api.github.com/search/code?q=addClass+user%3Amozilla&page=1>; rel="first",
+    #           <https://api.github.com/search/code?q=addClass+user%3Amozilla&page=13>; rel="prev"'
+    #
+    # ```
+    #
+    # If the response has no list header, then that means we got all the records
+    # and there's just that one page.
+    #
+    # If the response has a list header, the value will contain at least the
+    # "last" relation.
+    #
+    # Unfortunatly, the only way to parse it is via regex.
     links_string
     |> String.split(", ")
     |> Enum.map(fn link ->
+      # Searches for `rel=`
       rel = Regex.run(~r{rel="([a-z]+)"}, link) |> List.last
+      # Searches for the following variations:
+      # ```
+      # ?page={match}>
+      # ?page={match}&...
+      # &page={match}>
+      # &page={match}&...
+      # ```
       page = Regex.run(~r{[&/?]page=([^>&]+)}, link) |> List.last |> String.to_integer
 
       {rel, page}