Add documentation

lib/exquickbooks.ex

@@ -1,23 +1,63 @@
 defmodule ExQuickBooks do
   @moduledoc """
   API client for QuickBooks Online.
+
+  ## Configuration
+
+  You can configure the application through `Mix.Config`:
+
+      config :exquickbooks,
+        callback_url: "http://example.com/callback",
+        consumer_key: "key",
+        consumer_secret: "secret",
+        use_production_api: true
+
+  ### Accepted configuration keys
+
+  #### `:callback_url`
+
+  Required. An absolute URL where the user is redirected after authorising your
+  application. See the documentation for `ExQuickBooks.OAuth` for more details.
+
+  #### `:consumer_key`, `:consumer_secret`
+
+  Required. OAuth consumer credentials which you can get for your application
+  at <https://developer.intuit.com/getstarted>.
+
+  Please note that there are different credentials for the sandbox and
+  production APIs.
+
+  #### `:use_production_api`
+
+  Optional, `false` by default. Set to `false` to use the QuickBooks Sandbox,
+  `true` to connect to the production APIs.
+
+  ### Reading environment variables
+
+  If you store configuration in the system’s environment variables, you can
+  have ExQuickBooks read them at runtime:
+
+      config :exquickbooks,
+        consumer_key: {:system, "EXQUICKBOOKS_KEY"},
+        consumer_secret: {:system, "EXQUICKBOOKS_SECRET"}
+
+  This syntax works for binary and boolean values. Booleans are parsed from
+  `"true"` and `"false"`, otherwise the binary is used as is.
   """
 
   @backend_config :backend
   @callback_config :callback_url
   @credential_config [:consumer_key, :consumer_secret]
   @use_production_api_config :use_production_api
 
-  @doc """
-  Returns the Intuit OAuth API URL.
-  """
+  # Returns the Intuit OAuth API URL.
+  @doc false
   def oauth_api do
     "https://oauth.intuit.com/oauth/v1/"
   end
 
-  @doc """
-  Returns the QuickBooks Accounting API URL.
-  """
+  # Returns the QuickBooks Accounting API URL.
+  @doc false
   def accounting_api do
     if get_env(@use_production_api_config, false) do
       "https://quickbooks.api.intuit.com/v3/"
@@ -26,9 +66,8 @@ defmodule ExQuickBooks do
     end
   end
 
-  @doc """
-  Returns the configured HTTP backend.
-  """
+  # Returns the configured HTTP backend.
+  @doc false
   def backend do
     case get_env(@backend_config) do
       backend when is_atom(backend) ->
@@ -40,9 +79,8 @@ defmodule ExQuickBooks do
     end
   end
 
-  @doc """
-  Returns the configured OAuth callback URL.
-  """
+  # Returns the configured OAuth callback URL.
+  @doc false
   def callback_url do
     case get_env(@callback_config) do
       url when is_binary(url) ->
@@ -54,9 +92,8 @@ defmodule ExQuickBooks do
     end
   end
 
-  @doc """
-  Returns the configured OAuth credentials.
-  """
+  # Returns the configured OAuth credentials.
+  @doc false
   def credentials do
     for k <- @credential_config do
       case get_env(k) do

lib/exquickbooks/oauth.ex

@@ -1,13 +1,49 @@
 defmodule ExQuickBooks.OAuth do
   @moduledoc """
-  QuickBooks OAuth API.
+  Authentication functions for OAuth 1.0a.
+
+  QuickBooks uses the three-legged OAuth 1.0a flow. For a human-readable
+  overview of the whole flow and how to implement it, see e.g.
+  [oauthbible.com](http://oauthbible.com/#oauth-10a-three-legged).
+
+  ## Request token
+
+  To start the authentication flow, your application needs to get a request
+  token and secret using `get_request_token/0`:
+
+      {:ok,
+       %{"oauth_token" => oauth_token,
+         "oauth_token_secret" => oauth_token_secret},
+       redirect_url} = ExQuickBooks.get_request_token
+
+  That function will also give you the URL where you should redirect the user
+  to authorise your application to access their QuickBooks data. After that
+  step they will be redirected to the `:callback_url` you’ve set in the
+  configuration.
+
+  If you need to persist data (such as the request token and secret) between
+  this request and the callback, you could store that data e.g. in the current
+  user’s (encrypted!) session.
   """
 
   alias ExQuickBooks.OAuthEndpoint, as: Endpoint
 
   @doc """
   Retrieves a new OAuth request token.
+
+  Returns the token response and a URL where your application should redirect
+  the user. The token response contains the following keys:
+
+  - `"oauth_token"` -
+    The token associated with the user.
+  - `"oauth_token_secret"` -
+    The token secret associated with the user.
+
+  Note that the redirect URL is prepopulated with the token.
   """
+  @type request_token     :: %{required(String.t) => String.t}
+  @type redirect_url      :: String.t
+  @spec get_request_token :: {:ok, request_token, redirect_url} | {:error, any}
   def get_request_token do
     options = [params: [{"oauth_callback", ExQuickBooks.callback_url}]]
 

mix.exs

@@ -5,12 +5,20 @@ defmodule ExQuickBooks.Mixfile do
     [app: :exquickbooks,
      version: "0.2.0",
      elixir: "~> 1.4",
-     description: description(),
-     package: package(),
-     deps: deps(),
+
+     # Compilation
      elixirc_paths: elixirc_paths(Mix.env),
      build_embedded: Mix.env == :prod,
      start_permanent: Mix.env == :prod,
+
+     # Packaging
+     name: "ExQuickBooks",
+     description: description(),
+     package: package(),
+     deps: deps(),
+     docs: docs(),
+
+     # Test coverage
      test_coverage: [tool: ExCoveralls],
      preferred_cli_env: [coveralls: :test]]
   end
@@ -39,6 +47,10 @@ defmodule ExQuickBooks.Mixfile do
      links: %{"GitHub" => "https://github.com/Boulevard/ExQuickBooks"}]
   end
 
+  defp docs do
+    [main: ExQuickBooks]
+  end
+
   # Dependencies can be Hex packages:
   #
   #   {:my_dep, "~> 0.3.0"}