Misc doc changes

.formatter.exs

@@ -1,3 +1,4 @@
+# Used by "mix format"
 [
-  inputs: ["mix.exs", "{config,lib,test}/**/*.{ex,exs}"]
+  inputs: ["{mix,.formatter}.exs", "{config,lib,test}/**/*.{ex,exs}"]
 ]

.gitignore

@@ -1,24 +1,30 @@
-# vscode elixir_ls plugin artifacts
-/.elixir_ls
-
 # The directory Mix will write compiled artifacts to.
-/_build
+/_build/
 
 # If you run "mix test --cover", coverage assets end up here.
-/cover
+/cover/
 
 # The directory Mix downloads your dependencies sources to.
-/deps
+/deps/
+
+# Where third-party dependencies like ExDoc output generated docs.
+/doc/
 
-# Where 3rd-party dependencies like ExDoc output generated docs.
-/doc
+# Ignore .fetch files in case you like to edit your project deps locally.
+/.fetch
 
 # If the VM crashes, it generates a dump, let's ignore it too.
 erl_crash.dump
 
 # Also ignore archive artifacts (built via "mix archive.build").
 *.ez
 
+# Ignore package tarball (built via "mix hex.build").
+swarm-*.tar
+
+# Temporary files for e.g. tests.
+/tmp/
+
 # Intellij Files
 /.idea/
-/swarm.iml
+/swarm.iml

CHANGELOG.md

@@ -1,4 +1,6 @@
-## Next Release
+# Changelog
+
+## 3.2.0 (2018-02-01)
 
 ### Changed
 
@@ -16,7 +18,7 @@ N/A
 
 Don't attempt to hand-off or restart processes started with `Swarm.register_name/2` ([#63](https://github.com/bitwalker/swarm/pull/63)). Fixes #62.
 
-## 3.1
+## 3.1.0 (2017-11-15)
 
 ### Changed
 
@@ -37,7 +39,7 @@ Don't attempt to hand-off or restart processes started with `Swarm.register_name
 - Add local registration when restarted named process is already started but unknown locally ([#46](https://github.com/bitwalker/swarm/pull/46)).
 - Retry starting remote process when module not yet available on target node ([#56](https://github.com/bitwalker/swarm/pull/56)).
 
-## 2.0
+## 2.0.0 (2016-10-01)
 
 ### Removed
 

README.md

@@ -1,12 +1,18 @@
 # Swarm
 
-[![Hex.pm Version](http://img.shields.io/hexpm/v/swarm.svg?style=flat)](https://hex.pm/packages/swarm) [![Build Status](https://travis-ci.com/bitwalker/swarm.svg?branch=master)](https://travis-ci.com/bitwalker/swarm)
-
-**NOTE**: If you are upgrading from 1.0, be aware that the autoclustering functionality has been extracted
-to its own package, which you will need to depend on if you use that feature.
-The package is [libcluster](http://github.com/bitwalker/libcluster) and is available on
-[Hex](https://hex.pm/packages/libcluster). Please be sure to read over the README to make sure your
-config is properly updated.
+[![Build Status](https://travis-ci.com/bitwalker/swarm.svg?branch=master)](https://travis-ci.com/bitwalker/swarm)
+[![Module Version](https://img.shields.io/hexpm/v/swarm.svg)](https://hex.pm/packages/swarm)
+[![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/swarm/)
+[![Total Download](https://img.shields.io/hexpm/dt/swarm.svg)](https://hex.pm/packages/swarm)
+[![License](https://img.shields.io/hexpm/l/swarm.svg)](https://github.com/bitwalker/swarm/blob/master/LICENSE)
+[![Last Updated](https://img.shields.io/github/last-commit/bitwalker/swarm.svg)](https://github.com/bitwalker/swarm/commits/master)
+
+> **NOTE**: If you are upgrading from 1.0, be aware that the autoclustering
+> functionality has been extracted to its own package, which you will need to
+> depend on if you use that feature. The package is
+> [libcluster](http://github.com/bitwalker/libcluster) and is available on
+> [Hex](https://hex.pm/packages/libcluster). Please be sure to read over the
+> README to make sure your config is properly updated.
 
 Swarm is a global distributed registry, offering a feature set similar to that of `gproc`,
 but architected to handle dynamic node membership and large volumes of process registrations
@@ -31,19 +37,27 @@ for you!
 
 View the docs [here](https://hexdocs.pm/swarm).
 
-**PLEASE READ**: If you are giving Swarm a spin, it is important to understand that you can concoct scenarios whereby
-the registry appears to be out of sync temporarily, this is a side effect of an eventually consistent model and does not mean that
-Swarm is not working correctly, rather you need to ensure that applications you build on top of Swarm are written to embrace eventual
-consistency, such that periods of inconsistency are tolerated. For the most part though, the registry replicates extremely
-quickly, so noticeable inconsistency is more of an exception than a rule, but a proper distributed system should always be designed to
-tolerate the exceptions, as they become more and more common as you scale up. If however you notice extreme inconsistency or delayed
-replication, then it is possible it may be a bug, or performance issue, so feel free to open an issue if you are unsure, and we will gladly look into it.
+> **PLEASE READ**: If you are giving Swarm a spin, it is important to
+> understand that you can concoct scenarios whereby the registry appears to be
+> out of sync temporarily, this is a side effect of an eventually consistent
+> model and does not mean that Swarm is not working correctly, rather you need
+> to ensure that applications you build on top of Swarm are written to embrace
+> eventual consistency, such that periods of inconsistency are tolerated. For
+> the most part though, the registry replicates extremely quickly, so
+> noticeable inconsistency is more of an exception than a rule, but a proper
+> distributed system should always be designed to tolerate the exceptions, as
+> they become more and more common as you scale up. If however you notice
+> extreme inconsistency or delayed replication, then it is possible it may be a
+> bug, or performance issue, so feel free to open an issue if you are unsure,
+> and we will gladly look into it.
 
 ## Installation
 
 ```elixir
 defp deps do
-  [{:swarm, "~> 3.0"}]
+  [
+    {:swarm, "~> 3.0"}
+  ]
 end
 ```
 
@@ -320,10 +334,6 @@ defmodule MyApp.ExampleUsage do
 end
 ```
 
-## License
-
-MIT
-
 ## Testing
 
 `mix test` runs a variety of tests, most of them use a cluster of
@@ -343,8 +353,13 @@ If you don't have `epmd` running you can start it using the following command:
 
     epmd -daemon
 
-
 ## TODO
 
 - automated testing (some are present)
 - QuickCheck model
+
+## Copyright and License
+
+Copyright (c) 2016 Paul Schoenfelder
+
+Released under the MIT License, which can be found in the repository in [`LICENSE.md`](https://github.com/bitwalker/swarm/blob/master/LICENSE.md).

lib/swarm/distribution/strategy.ex

@@ -5,13 +5,15 @@ defmodule Swarm.Distribution.Strategy do
   via the `libring` library.
 
   Custom strategies are expected to return a datastructure or pid which will be
-  passed along to any functions which need to manipulate the current distribution state.
-  This can be either a plain datastructure (as is the case with the libring-based strategy),
-  or a pid which your strategy module then uses to call a process in your own supervision tree.
+  passed along to any functions which need to manipulate the current
+  distribution state.  This can be either a plain datastructure (as is the case
+  with the libring-based strategy), or a pid which your strategy module then
+  uses to call a process in your own supervision tree.
 
-  For efficiency reasons, it is highly recommended to use plain datastructures rather than a
-  process for storing the distribution state, because it has the potential to become a bottleneck otherwise,
-  however this is really up to the needs of your situation, just know that you can go either way.
+  For efficiency reasons, it is highly recommended to use plain datastructures
+  rather than a process for storing the distribution state, because it has the
+  potential to become a bottleneck otherwise, however this is really up to the
+  needs of your situation, just know that you can go either way.
   """
   alias Swarm.Distribution.Ring, as: RingStrategy
 
@@ -56,6 +58,7 @@ defmodule Swarm.Distribution.Strategy do
 
   @doc """
   Adds a list of nodes to the state of the current distribution strategy.
+
   The node list can be composed of both node names (atoms) or tuples containing
   a node name and a weight for that node.
   """

lib/swarm/logger.ex

@@ -2,7 +2,7 @@ defmodule Swarm.Logger do
   @moduledoc false
 
   @doc """
-  Formats a log message to include info on which node swarm is running on
+  Formats a log message to include info on which node swarm is running on.
   """
   @spec format(String.t()) :: String.t()
   def format(message), do: "[swarm on #{Node.self()}] #{message}"

lib/swarm/registry.ex

@@ -111,7 +111,7 @@ defmodule Swarm.Registry do
   end
 
   @doc """
-  Inserts a new registration, and returns true if successful, or false if not
+  Inserts a new registration, and returns true if successful, or false if not.
   """
   @spec new(Entry.entry()) :: boolean
   def new(entry() = reg) do

lib/swarm/tracker/crdt.ex

@@ -16,7 +16,7 @@ defmodule Swarm.IntervalTreeClock do
           | {int_tuple, int_tuple}
 
   @doc """
-  Creates a new interval tree clock
+  Creates a new interval tree clock.
   """
   @spec seed() :: __MODULE__.t()
   def seed(), do: {1, 0}
@@ -45,7 +45,7 @@ defmodule Swarm.IntervalTreeClock do
   def peek({_i, e}), do: {0, e}
 
   @doc """
-  Records an event on the given clock
+  Records an event on the given clock.
   """
   @spec event(__MODULE__.t()) :: __MODULE__.t()
   def event({i, e}) do
@@ -69,10 +69,10 @@ defmodule Swarm.IntervalTreeClock do
 
   @doc """
   Compares two clocks.
-  If :eq is returned, the two clocks are causally equivalent
-  If :lt is returned, the first clock is causally dominated by the second
-  If :gt is returned, the second clock is causally dominated by the first
-  If :concurrent is returned, the two clocks are concurrent (conflicting)
+  If :eq is returned, the two clocks are causally equivalent.
+  If :lt is returned, the first clock is causally dominated by the second.
+  If :gt is returned, the second clock is causally dominated by the first.
+  If :concurrent is returned, the two clocks are concurrent (conflicting).
   """
   @spec compare(__MODULE__.t(), __MODULE__.t()) :: :lt | :gt | :eq | :concurrent
   def compare(a, b) do
@@ -88,13 +88,13 @@ defmodule Swarm.IntervalTreeClock do
   end
 
   @doc """
-  Encodes the clock as a binary
+  Encodes the clock as a binary.
   """
   @spec encode(__MODULE__.t()) :: binary
   def encode({i, e}), do: :erlang.term_to_binary({i, e})
 
   @doc """
-  Decodes the clock from a binary
+  Decodes the clock from a binary.
   """
   @spec decode(binary) :: {:ok, __MODULE__.t()} | {:error, {:invalid_clock, term}}
   def decode(b) when is_binary(b) do
@@ -108,7 +108,7 @@ defmodule Swarm.IntervalTreeClock do
   end
 
   @doc """
-  Returns the length of the encoded binary representation of the clock
+  Returns the length of the encoded binary representation of the clock.
   """
   @spec len(__MODULE__.t()) :: non_neg_integer
   def len(d), do: :erlang.size(encode(d))

lib/swarm/tracker/tracker.ex

@@ -60,14 +60,16 @@ defmodule Swarm.Tracker do
   @doc """
   Hand off all the processes running on the given worker to the remaining nodes in the cluster.
   This can be used to gracefully shut down a node.
-  Note that if you don't shut down the node after the handoff a rebalance can lead to processes being scheduled on it again.
+  Note that if you don't shut down the node after the handoff a rebalance can
+  lead to processes being scheduled on it again.
   In other words the handoff doesn't blacklist the node for further rebalances.
   """
   def handoff(worker_name, state),
     do: GenStateMachine.call(__MODULE__, {:handoff, worker_name, state}, :infinity)
 
   @doc """
   Tracks a process (pid) with the given name.
+
   Tracking processes with this function will *not* restart the process when
   its parent node goes down, or shift the process to other nodes if the cluster
   topology changes. It is strictly for global name registration.
@@ -77,12 +79,21 @@ defmodule Swarm.Tracker do
 
   @doc """
   Tracks a process created via the provided module/function/args with the given name.
-  The process will be distributed on the cluster based on the implementation of the configured distribution strategy.
-  If the process' parent node goes down, it will be restarted on the new node which owns its keyspace.
+
+  The process will be distributed on the cluster based on the implementation of
+  the configured distribution strategy.
+
+  If the process' parent node goes down, it will be restarted on the new node
+  which owns its keyspace.
+
   If the cluster topology changes, and the owner of its keyspace changes, it will be shifted to
   the new owner, after initiating the handoff process as described in the documentation.
-  A track call will return an error tagged tuple, `{:error, :no_node_available}`, if there is no node available to start the process.
-  Provide a timeout value to limit the track call duration. A value of `:infinity` can be used to block indefinitely.
+
+  A track call will return an error tagged tuple, `{:error,
+  :no_node_available}`, if there is no node available to start the process.
+
+  Provide a timeout value to limit the track call duration. A value of
+  `:infinity` can be used to block indefinitely.
   """
   def track(name, m, f, a, timeout) when is_atom(m) and is_atom(f) and is_list(a),
     do: GenStateMachine.call(__MODULE__, {:track, name, %{mfa: {m, f, a}}}, timeout)
@@ -94,7 +105,8 @@ defmodule Swarm.Tracker do
     do: GenStateMachine.call(__MODULE__, {:untrack, pid}, :infinity)
 
   @doc """
-  Adds some metadata to the given process (pid). This is primarily used for tracking group membership.
+  Adds some metadata to the given process (pid). This is primarily used for
+  tracking group membership.
   """
   def add_meta(key, value, pid) when is_pid(pid),
     do: GenStateMachine.call(__MODULE__, {:add_meta, key, value, pid}, :infinity)