Merge pull request #19 from toniqsystems/nm-explicit-params

make explicit what has been forgotten

Author: NeilMenne

README.md

@@ -1,22 +1,21 @@
 # HLClock
 
-[![Build Status](https://travis-ci.org/toniqsystems/hlclock.svg?branch=master)](https://travis-ci.org/toniqsystems/hlclock)
+[![Build Status](https://travis-ci.org/toniqsystems/hlclock.svg?branch=master)](https://travis-ci.org/toniqsystems/hlclock) [![Hex pm](http://img.shields.io/hexpm/v/hlclock.svg?style=flat)](https://hex.pm/packages/hlclock)
 
 ## About
 
 Hybrid Logical Clocks (HLC) provide a one-way causality detection using a
 combination of logical time and physical NTP timestamp. This library adds an
 additional mechanism for resolving conflicts between timestamps by adding a
-unique node id to each HLC.
+unique node id to each HLC timestamp.
 
 These timestamps can be used in place of standard NTP timestamps in order to
 provide consistent snapshots and causality tracking. HLCs have a fixed space
 requirement and are bounded close to physical timestamps.
 
 ## Installation
 
-Now [available in Hex](https://hex.pm/docs/publish), the package can be installed
-by adding `hlclock` to your list of dependencies in `mix.exs`:
+First, add `HLClock` to your `mix.exs` dependencies.
 
 ```elixir
 def deps do
@@ -26,19 +25,20 @@ end
 
 ## Usage
 
-In order to generate HLCs you'll need an HLClock process:
+Starting in version 1.0.0, the `HLClock.Server` is not started as an application
+automatically. `HLClock.start_link/1` is as a short cut to manually start a process:
 
 ```elixir
 {:ok, clock} = HLClock.start_link()
 {:ok, ts} = HLClock.send_timestamp(clock)
 ```
 
-You can also supervise clock processes:
+In practice, it is best to have a single `HLClock` running on any given node.
+Toward that end, `HLClock` also provides a `child_spec` that accepts all
+standard `GenServer` opts:
 
 ```elixir
 children = [
   {HLClock, name: :my_hlc_server},
 ]
 ```
-
-`HLClock.start_link/1` accepts all arguments for `GenServer`.

lib/hlclock.ex

@@ -15,6 +15,19 @@ defmodule HLClock do
   """
   alias HLClock.Timestamp
 
+  @doc """
+  Returns a specification to start an `HLClock.Server` under a supervisor
+
+  In addition to standard `GenServer` opts, this allows for two other
+  options to be passed to the underlying server:
+
+  * `:node_id` - a zero arity function returning a 64 bit integer for the node ID
+    or a constant value that was precomputed prior to starting; defaults to
+    `HLClock.NodeId.hash/0`
+  * `:max_drift` - the clock synchronization bound which is applied in either
+    direction (i.e. timestamps are too far in the past or too far in the
+    future); this value is in milliseconds and defaults to `300_000`
+  """
   def child_spec(opts) do
     %{
       id: __MODULE__,
@@ -45,7 +58,7 @@ defmodule HLClock do
   end
 
   @doc """
-  Functionally equivalent to using `send_timestamp/0`. This generates a timestamp
+  Functionally equivalent to using `send_timestamp/1`. This generates a timestamp
   for local causality tracking.
   """
   def now(server) do