Another documentation sweep

lib/crutches/integer.ex

@@ -7,9 +7,9 @@ defmodule Crutches.Integer do
   """
 
   @doc ~S"""
-  Return _just_ the ordinal of a number ("st", "nd", "rd", "th")
+  Return the ordinal of `n`. ("st", "nd", "rd", "th")
 
-  ## Examples
+  # Examples
 
       iex> Integer.ordinal(-1)
       "st"
@@ -43,9 +43,9 @@ defmodule Crutches.Integer do
 
 
   @doc ~S"""
-  Return the number and it's ordinal as a string
+  Return `n` and it's ordinal as a string.
 
-  ## Examples
+  # Examples
 
       iex> Integer.ordinalize(2)
       "2nd"
@@ -60,9 +60,9 @@ defmodule Crutches.Integer do
   def ordinalize(n) when is_integer(n), do: to_string(n) <> ordinal(n)
 
   @doc ~S"""
-  Check whether the integer is evenly divisible by the argument.
+  Check whether `n` is evenly divisible by `divisor`.
 
-  ## Examples
+  # Examples
 
       iex> Integer.multiple_of?(7, 3)
       false

lib/crutches/map.ex

@@ -7,15 +7,12 @@ defmodule Crutches.Map do
   """
 
   @doc """
-  Travel through a map by specifying a path, JSON-style.
-  First parameter is the map, second parameter is the path (either as a list or a string).
+  Travel through `map` according to a specified `path`.
 
-  Set the third parameter to `true` if the keys of the map are `Strings`.
-  It otherwise defaults to `false`, where it assumes the keys are `atoms`.
+  The `path` is either a list or a string.  Pass in a string if the keys in
+  `map` are strings, otherwise pass an atom (`:"parent.child"`).
 
-  Pass in a string if the keys are strings, otherwise pass an atom (`:"parent.child"`).
-
-  ## Examples
+  # Examples
 
       iex> data = %{
       ...>   "bio" => "Get BUSH now!",
@@ -50,7 +47,7 @@ defmodule Crutches.Map do
   The fetch version of get_path, where if the key is found returns
   `{:ok, value}`, and if not then `:error`.
 
-  ## Examples
+  # Examples
 
       iex> Map.fetch_path(%{ good: %{ bad: "ugly" } }, :"good.bad")
       {:ok, "ugly"}
@@ -70,7 +67,7 @@ defmodule Crutches.Map do
   Throwing version of fetch_path, that returns the value if the path has been
   successfully traversed, and if not then throws an error.
 
-  ## Examples
+  # Examples
 
       iex> Map.fetch_path!(%{ good: %{ bad: "ugly" }}, :"good.ugly")
       ** (KeyError) key :ugly not found in: %{bad: "ugly"}
@@ -92,10 +89,9 @@ defmodule Crutches.Map do
   end
 
   @doc ~S"""
-  Recursively traverse a (nested) hash and change the keys based on
-  the function provided.
+  Recursively traverse `map` and change the keys based on `fun`.
 
-  ## Examples
+  # Examples
 
       iex> map = %{"hello" => %{"goodbye" => 1}, "akuna" => "matata"}
       iex> Map.dkeys_update(map, fn (key) -> String.to_atom(key) end)
@@ -106,8 +102,8 @@ defmodule Crutches.Map do
       %{hello: %{akuna: "matata", goodbye: 1, hello: %{akuna: "matata", goodbye: 1}}, akuna: "matata"}
   """
   def dkeys_update(map, fun), do: dkeys_update(map, fun, %{})
-  def dkeys_update(map, _, acc) when map == %{}, do: acc
-  def dkeys_update(map, fun, acc) do
+  defp dkeys_update(map, _, acc) when map == %{}, do: acc
+  defp dkeys_update(map, fun, acc) do
     key = Map.keys(map) |> List.first
     case is_map(map[key]) do
       true -> value = dkeys_update(map[key], fun)

lib/crutches/option.ex

@@ -2,69 +2,63 @@ defmodule Crutches.Option do
   @moduledoc ~S"""
   Convenience functions for dealing with funciton option handling.
 
-  It provides a mechanism for declaring default options and merging these with
+  This provides a mechanism for declaring default options and merging these with
   those given by any caller.
 
-  ## Usage
+  # Usage
 
   When you have a function with the following head, the use of this module may
   be beneficial. Of course you can have as much required `args` as you want.
   `options` is a keyword list.
 
-  ```
-    def foo(args, options)
-  ```
+      def foo(args, options)
 
   Usage is pretty simple. Declare a module attribute with the name of your
   function. It should be a keyword list with the keys `:valid` and `:defaults`.
   `:valid` should contain a list of atoms. `:defaults` should contain another
   keyword list with the default options of your function.
 
-  Example:
+  ## Example
 
-  ```
-  @function_name [
-    valid: ~w(foo bar)a
-    defaults: [
-      foo: "some",
-      bar: "value"
-    ]
-  ]
-  ```
+      @function_name [
+        valid: ~w(foo bar)a
+        defaults: [
+          foo: "some",
+          bar: "value"
+        ]
+      ]
 
   When this is done, you can declare your function head like this:
 
-  ```
-  def function_name(args, opts \\ @function_name[:defaults])
-  ```
+      def function_name(args, opts \\ []])
 
   And then you're all set to actually write the meat of your function. (You of
   course don't need a function head if your function only consists of one clause.)
 
-  ```
-  def function_name(args, opts) do
-    # This validates and merges the options, throwing on error.
-    opts = Crutches.Options.combine!(opts, @function_name)
+      def function_name(args, opts) do
+        # This validates and merges the options, throwing on error.
+        opts = Crutches.Options.combine!(opts, @function_name)
 
-    # You can now use the options.
-    do_something_with(opts[:foo])
-  end
-  ```
+        # You can now use the options.
+        do_something_with(opts[:foo])
+      end
   """
 
   @doc ~S"""
   Validates the `opts` keyword list according to `config`, combines defaults.
 
   For intended use see the module documentation.
 
+  # Config variable
+
   The `config` parameter should be a keyword list with the following keys:
 
-    - `:valid`    -- list of atoms of options that your function accepts.
-    - `:defaults` -- keyword list of default values for the options in `:valid`
+    - `:valid` ([atom]) --- Parameters that your function accepts.
+    - `:defaults` ([atom: any]) --- Default values for the options in `:valid`.
 
   Returns `{:ok, opts}` on succes, `{:error, invalid_keys}` on failure.
 
-  ### Examples
+  # Examples
 
       iex> config = [valid: ~w(foo bar)a, defaults: [foo: "some", bar: "value"]]
       iex> Option.combine([foo: "another"], config)
@@ -84,7 +78,7 @@ defmodule Crutches.Option do
   This function is the same as `combine/2`, except it returns `options` on
   validation succes and throws `ArgumentError` on validation failure.
 
-  ### Examples
+  # Examples
 
       iex> config = [valid: ~w(foo bar)a, defaults: [foo: "some", bar: "value"]]
       iex> Option.combine!([foo: "another"], config)
@@ -109,7 +103,7 @@ defmodule Crutches.Option do
   `config[:defaults]` as the first parameter and the validated `opts` as the
   second.
 
-  ### Examples
+  # Examples
 
   Contrived example showing of the use of `combinator`.
 
@@ -129,7 +123,7 @@ defmodule Crutches.Option do
   @doc ~S"""
   Throwing version of `combine/3`
 
-  ### Examples
+  # Examples
 
       iex> config = [valid: ~w(foo bar)a, defaults: [foo: "some", bar: "value"]]
       iex> combinator = fn(_, _) -> nil end
@@ -146,11 +140,12 @@ defmodule Crutches.Option do
   end
 
   @doc ~S"""
-  Checks a keyword list for unexpected keys, by using a default list of keys.
+  Checks a `opts` for keys not in `valid`.
+
   Returns {:ok, []} if all options are kosher, otherwise {:error, list},
   where list is a list of all invalid keys.
 
-  ## Examples
+  # Examples
 
       iex> Option.validate([good: "", good_opt: ""], [:good, :good_opt])
       {:ok, []}
@@ -170,7 +165,7 @@ defmodule Crutches.Option do
   @doc ~S"""
   Throwing version of `Option.validate`
 
-  ## Examples
+  # Examples
 
       iex> Option.validate!([good: "", bad: ""], [:good])
       ** (ArgumentError) invalid key bad
@@ -190,10 +185,11 @@ defmodule Crutches.Option do
   end
 
   @doc ~S"""
-  Checks a keyword list for unexpected keys, by using a default list of keys.
-  When a bad key is detected it returns false, else it returns true.
+  Check `opts` for keys not in `valid`.
+
+  Return `false` when a bad key is found, otherwise return `true`.
 
-  ## Examples
+  # Examples
 
       iex> Option.all_valid?([good: "", good_opt: ".", bad: "!"], [:good, :good_opt])
       false