add @doc comments to elixir_auth_google.ex functions for #10

README.md

@@ -31,14 +31,15 @@ Following best practices for security & privacy
 and avoiding complexity
 by having sensible defaults for all settings.
 
+
 > We built a lightweight solution
 that only does _one_ thing
 and is easy for complete beginners to understand/use. <br />
 There were already _several_ available options
 for adding Google Auth to apps on
 [hex.pm/packages?search=google](https://hex.pm/packages?search=google) <br />
 that all added _far_ too implementation steps (complexity)
-and had incomplete documentation and testing. <br />
+and had incomplete documentation (**`@doc false`**) and testing. <br />
 e.g:
 [github.com/googleapis/elixir-google-api](https://github.com/googleapis/elixir-google-api)
 which is a
@@ -124,7 +125,7 @@ GOOGLE_CLIENT_SECRET=MHxv6-RGF5nheXnxh1b0LNDq
 They are just here for illustration purposes.
 
 
-## 3. Create a `GoogleAuthController` in your Project
+## 3. Create a `GoogleAuthController` in your Project 📝
 
 
 Create a new endpoint matching the `google_redirect_uri`.
@@ -161,9 +162,10 @@ config :elixir_auth_google,
 
 
 
-## 4. Create the `/auth/google` Endpoint 📝
+## 4. Create the `/auth/google/callback` Endpoint 📍
 
-Open your **`router.ex`** file and add the `/auth/google` Endpoint
+Open your **`router.ex`** file
+and add the `/auth/google/callback` endpoint.
 
 
 
@@ -174,16 +176,22 @@ Open your **`router.ex`** file and add the `/auth/google` Endpoint
 > Example code:
 
 
+# _Done_!
+
+
+
 <br /> <br />
 
 ## _Implementation_ Details 💡
 
+If you want to dive a bit deeper into _understanding_ how this package works,
+You can read and grok the code in under 10 minutes:
+[`/lib/elixir_auth_google.ex`](https://github.com/dwyl/elixir-auth-google/blob/master/lib/elixir_auth_google.ex)
 
 If you are using the the **`elixir_auth_google`** package
 in a Phoenix application (_the most popular use case_),
 these implementation details might be helpful.
 
-
 ### Generating Phoenix Session Key (`SECRET_KEY_BASE`) and Encryption Keys
 
 To generate a cryptographically secure session key,

lib/elixir_auth_google.ex

@@ -1,12 +1,21 @@
 defmodule ElixirAuthGoogle do
   @moduledoc """
-  Minimalist Google OAuth Authentication for Elixir Apps
+  Minimalist Google OAuth Authentication for Elixir Apps.
+  Extensively tested, documented, maintained and in active use in production.
   """
   @httpoison Application.get_env(:elixir_auth_google, :httpoison) || HTTPoison
   @google_auth_url "https://accounts.google.com/o/oauth2/v2/auth?response_type=code"
   @google_token_url "https://oauth2.googleapis.com/token"
   @google_user_profile "https://www.googleapis.com/oauth2/v3/userinfo"
 
+  @doc """
+  generate_oauth_url/0 creates the Google OAuth2 URL with client_id, scope and
+  redirect_uri which is the URL Google will redirect to when auth is successful.
+  This is the URL you need to use for your "Login with Google" button.
+  See step 5 of the instructions.
+  e.g:
+  https://accounts.google.com/o/oauth2/v2/auth?response_type=code&client_id=123
+  """
   def generate_oauth_url do
     client_id = Application.get_env(:elixir_auth_google, :google_client_id)
     scope = Application.get_env(:elixir_auth_google, :google_scope ) || "profile"
@@ -15,6 +24,11 @@ defmodule ElixirAuthGoogle do
     "#{@google_auth_url}&client_id=#{client_id}&scope=#{scope}&redirect_uri=#{redirect_uri}"
   end
 
+  @doc """
+  get_token/1 encodes the secret keys and authorization code returned by Google
+  and issues an HTTP request to get a person's profile data.
+  TODO: we still need to handle the various failure conditions >> issues/16
+  """
   def get_token(code) do
     body = Poison.encode!(
       %{ client_id: Application.get_env(:elixir_auth_google, :google_client_id),
@@ -28,12 +42,23 @@ defmodule ElixirAuthGoogle do
     |> parse_body_response()
   end
 
+  @doc """
+  get_user_profile/1 requests the Google User's userinfo profile data
+  providing the access_token received in the `get_token/1` above.
+  invokes `parse_body_response/1` to decode the JSON data.
+  TODO: we still need to handle the various failure conditions >> issues/16
+  At this point the types of errors we expect are HTTP 40x/50x responses.
+  """
   def get_user_profile(token) do
     "#{@google_user_profile}?access_token=#{token}"
     |> @httpoison.get()
     |> parse_body_response()
   end
 
+  @doc """
+  parse_body_response/1 parses the response returned by Google
+  so your app can use the resulting JSON.
+  """
   defp parse_body_response({:error, err}), do: {:error, err}
   defp parse_body_response({:ok, response}) do
     body = Map.get(response, :body)