Misc doc changes (#73)

List of changes:

- Mix format module config
- Add common sourse url
- Set and use latest ex_doc
- Set source reference by tagged version
- Fix markdown
- Revise documentation
- Add license section
- Mix format module config
- Badges and more badges!
- Update gitignore

Author: kianmeng

.gitignore

@@ -1,9 +1,31 @@
-/_build
-/deps
-/doc
-/docs
+# The directory Mix will write compiled artifacts to.
+/_build/
+
+# If you run "mix test --cover", coverage assets end up here.
+/cover/
+
+# The directory Mix downloads your dependencies sources to.
+/deps/
+
+# Where third-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
-mix.lock
+
+# Ignore package tarball (built via "mix hex.build").
+file_system-*.tar
+
+# Temporary files for e.g. tests
+/tmp
+
+# Misc
 /priv/mac_listener
 /priv/kqueue
+mix.lock

README.md

@@ -1,22 +1,29 @@
-FileSystem
-=========
+# FileSystem
 
-A file change watcher wrapper based on [fs](https://github.com/synrc/fs)
+[![Module Version](https://img.shields.io/hexpm/v/file_system.svg)](https://hex.pm/packages/file_system)
+[![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/file_system/)
+[![Total Download](https://img.shields.io/hexpm/dt/file_system.svg)](https://hex.pm/packages/file_system)
+[![License](https://img.shields.io/hexpm/l/file_system.svg)](https://github.com/falood/file_system/blob/master/LICENSE)
+[![Last Updated](https://img.shields.io/github/last-commit/falood/file_system.svg)](https://github.com/falood/file_system/commits/master)
+
+An Elixir file change watcher wrapper based on
+[FS](https://github.com/synrc/fs), the native file system listener.
 
 ## System Support
 
-- Mac fsevent
-- Linux, FreeBSD and OpenBSD inotify
-- Windows inotify-win
+- MacOS - [fsevent](https://github.com/thibaudgg/rb-fsevent)
+- GNU/Linux, FreeBSD and OpenBSD - [inotify](https://github.com/rvoicilas/inotify-tools/wiki)
+- Windows - [inotify-win](https://github.com/thekid/inotify-win)
 
-NOTE:
+On MacOS 10.14, to compile `mac_listener`, run:
 
-        On Linux, FreeBSD and OpenBSD you need to install inotify-tools.
-        On Macos 10.14, you need run `open /Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pkg` to compile `mac_listener`.
+```console
+open /Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pkg
+```
 
 ## Usage
 
-Put `file_system` in the `deps` and `application` part of your mix.exs
+Put `:file_system` in the `deps` and `application` part of your `mix.exs`:
 
 ``` elixir
 defmodule Excellent.Mixfile do
@@ -35,7 +42,6 @@ defmodule Excellent.Mixfile do
 end
 ```
 
-
 ### Subscription API
 
 You can spawn a worker and subscribe to events from it:
@@ -52,17 +58,18 @@ or
 FileSystem.subscribe(:my_monitor_name)
 ```
 
-The pid you subscribed from will now receive messages like
+The `pid` you subscribed from will now receive messages like:
 
 ```
 {:file_event, worker_pid, {file_path, events}}
 ```
 and
+
 ```
 {:file_event, worker_pid, :stop}
 ```
 
-### Example with GenServer
+### Example Using GenServer
 
 ```elixir
 defmodule Watcher do
@@ -78,27 +85,41 @@ defmodule Watcher do
     {:ok, %{watcher_pid: watcher_pid}}
   end
 
-  def handle_info({:file_event, watcher_pid, {path, events}}, %{watcher_pid: watcher_pid}=state) do
-    # YOUR OWN LOGIC FOR PATH AND EVENTS
+  def handle_info({:file_event, watcher_pid, {path, events}}, %{watcher_pid: watcher_pid} = state) do
+    # Your own logic for path and events
     {:noreply, state}
   end
 
-  def handle_info({:file_event, watcher_pid, :stop}, %{watcher_pid: watcher_pid}=state) do
-    # YOUR OWN LOGIC WHEN MONITOR STOP
+  def handle_info({:file_event, watcher_pid, :stop}, %{watcher_pid: watcher_pid} = state) do
+    # Your own logic when monitor stop
     {:noreply, state}
   end
 end
 ```
 
+## Backend Options
 
-## Tweaking behaviour via extra arguments
-
-For each platform, you can pass extra arguments to the underlying listener process.
+For each platform, you can pass extra options to the underlying listener
+process.
 
-Each backend support different extra arguments, check backend module documentation for more information.
+Each backend supports different extra options, check backend module
+documentation for more details.
 
-Here is an example to get instant notifications on file changes for Mac OS X:
+Here is an example to get instant notifications on file changes for MacOS:
 
 ```elixir
 FileSystem.start_link(dirs: ["/path/to/some/files"], latency: 0, watch_root: true)
 ```
+
+## License
+
+Copyright (C) 2016 Xiangrong Hao
+
+Everyone is permitted to copy and distribute verbatim or modified
+copies of this license document, and changing it is allowed as long
+as the name is changed.
+
+           DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+  TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+ 0. You just DO WHAT THE FUCK YOU WANT TO.

lib/file_system.ex

@@ -1,49 +1,59 @@
 defmodule FileSystem do
-  @moduledoc File.read!("README.md")
+  @moduledoc """
+  A `GenServer` process to watch file system changes.
+
+  The process receives data from Port, parse event, and send it to the worker
+  process.
+  """
 
   @doc """
+  Starts a `GenServer` process and linked to the current process.
+
   ## Options
 
-    * `:dirs` ([string], required), the dir list to monitor
+    * `:dirs` ([string], required), the list of directory to monitor.
 
-    * `:backend` (atom, optional), default backends: `:fs_mac`
-      for `macos`, `:fs_inotify` for `linux`, `freebsd` and `openbsd`,
-      `:fs_windows` for `windows`
+    * `:backend` (atom, optional), default backends: `:fs_mac`. Available
+      backends: `:fs_mac`, `:fs_inotify`, and `:fs_windows`.
 
-    * `:name` (atom, optional), `name` can be used to subscribe as
-      the same as pid when the `name` is given. The `name` should
-      be the name of worker process.
+    * `:name` (atom, optional), the `name` of the worker process to subscribe
+      to the file system listerner. Alternative to using `pid` of the worker
+      process.
 
-    * All rest options will treated as backend options. See backend
-      module documents for more details.
+    * Additional backend implementation options. See backend module documents
+      for more details.
 
-  ## Example
+  ## Examples
 
-  Simple usage:
+  Start monitoring `/tmp/fs` directory using the default `:fs_mac` backend of
+  the current process:
 
       iex> {:ok, pid} = FileSystem.start_link(dirs: ["/tmp/fs"])
       iex> FileSystem.subscribe(pid)
 
-  Get instant notifications on file changes for Mac OS X:
+  Get instant (`latench: 0`) notifications on file changes:
 
       iex> FileSystem.start_link(dirs: ["/path/to/some/files"], latency: 0)
 
-  Named monitor with specified backend:
+  Minitor a directory by a process name:
 
       iex> FileSystem.start_link(backend: :fs_mac, dirs: ["/tmp/fs"], name: :worker)
       iex> FileSystem.subscribe(:worker)
+
   """
   @spec start_link(Keyword.t) :: GenServer.on_start()
   def start_link(options) do
     FileSystem.Worker.start_link(options)
   end
 
   @doc """
-  Register the current process as a subscriber of a file_system worker.
-  The pid you subscribed from will now receive messages like
+  Register the current process as a subscriber of a `file_system` worker.
+
+  The `pid` you subscribed from will now receive messages like:
 
       {:file_event, worker_pid, {file_path, events}}
       {:file_event, worker_pid, :stop}
+
   """
   @spec subscribe(GenServer.server) :: :ok
   def subscribe(pid) do

lib/file_system/backend.ex

@@ -2,17 +2,21 @@ require Logger
 
 defmodule FileSystem.Backend do
   @moduledoc """
-  FileSystem Backend Behaviour.
+  A behaviour module for implementing different file system backend.
   """
 
   @callback bootstrap() :: :ok | {:error, atom()}
   @callback supported_systems() :: [{atom(), atom()}]
   @callback known_events() :: [atom()]
 
   @doc """
-  Get and validate backend module, return `{:ok, backend_module}` when success and
-  return `{:error, reason}` when fail.
-  When `nil` is given, will return default backend by os.
+  Get and validate backend module.
+
+  Returns `{:ok, backend_module}` upon success and `{:error, reason}` upon
+  failure.
+
+  When `nil` is given, will return default backend by OS.
+
   When a custom module is given, make sure `start_link/1`, `bootstrap/0` and
   `supported_system/0` are defnied.
   """

lib/file_system/backends/fs_inotify.ex

@@ -2,24 +2,35 @@ require Logger
 
 defmodule FileSystem.Backends.FSInotify do
   @moduledoc """
+  File system backend for GNU/Linux, FreeBSD, and OpenBSD.
+
   This file is a fork from https://github.com/synrc/fs.
-  FileSystem backend for linux, freebsd and openbsd, a GenServer receive data from Port, parse event
-  and send it to the worker process.
-  Need `inotify-tools` installed to use this backend.
 
   ## Backend Options
 
-    * `:recursive` (bool, default: true), monitor directories and their contents recursively
+    * `:recursive` (bool, default: true), monitor directories and their contents recursively.
 
   ## Executable File Path
 
-  The default behaivour to find executable file is finding `inotifywait` from `$PATH`, there're two ways to custom it, useful when run `:file_system` with escript.
+  Useful when running `:file_system` with escript.
+
+  The default listener executable file is found through finding `inotifywait` from
+  `$PATH`.
+
+  Two ways to customize the executable file path:
+
+    * Module config with `config.exs`:
+
+      ```elixir
+      config :file_system, :fs_inotify,
+        executable_file: "YOUR_EXECUTABLE_FILE_PATH"`
+      ```
 
-    * config with `config.exs`
-      `config :file_system, :fs_inotify, executable_file: "YOUR_EXECUTABLE_FILE_PATH"`
+    * System environment variable:
 
-    * config with `FILESYSTEM_FSINOTIFY_EXECUTABLE_FILE` os environment
-      FILESYSTEM_FSINOTIFY_EXECUTABLE_FILE=YOUR_EXECUTABLE_FILE_PATH
+      ```
+      export FILESYSTEM_FSINOTIFY_EXECUTABLE_FILE="YOUR_EXECUTABLE_FILE_PATH"`
+      ```
   """
 
   use GenServer

lib/file_system/backends/fs_mac.ex

@@ -2,35 +2,52 @@ require Logger
 
 defmodule FileSystem.Backends.FSMac do
   @moduledoc """
+  File system backend for MacOS.
+
+  The built-in executable file will be compile upon first use.
+
   This file is a fork from https://github.com/synrc/fs.
-  FileSysetm backend for macos, a GenServer receive data from Port, parse event
-  and send it to the worker process.
-  Will compile executable the buildin executable file when file the first time it is used.
 
   ## Backend Options
 
     * `:latency` (float, default: 0.5), latency period.
 
     * `:no_defer` (bool, default: false), enable no-defer latency modifier.
-      Works with latency parameter, Also check apple `FSEvent` api documents
-      https://developer.apple.com/documentation/coreservices/kfseventstreamcreateflagnodefer
+      Works with latency parameter.
+
+      See `FSEvent` API documents
+      https://developer.apple.com/documentation/coreservices/kfseventstreamcreateflagnodefer.
 
     * `:watch_root` (bool, default: false), watch for when the root path has changed.
       Set the flag `true` to monitor events when watching `/tmp/fs/dir` and run
-      `mv /tmp/fs /tmp/fx`. Also check apple `FSEvent` api documents
-      https://developer.apple.com/documentation/coreservices/kfseventstreamcreateflagwatchroot
+      `mv /tmp/fs /tmp/fx`.
+
+      See `FSEvent` API documents
+      https://developer.apple.com/documentation/coreservices/kfseventstreamcreateflagwatchroot.
 
-    * recursive is enabled by default, no option to disable it for now.
+    * recursive is enabled by default and it can'b be disabled for now.
 
   ## Executable File Path
 
-  The default executable file is `mac_listener` in `priv` dir of `:file_system` application, there're two ways to custom it, useful when run `:file_system` with escript.
+  Useful when running `:file_system` with escript.
+
+  The default listener executable file is `priv/mac_listener` within the folder of
+  `:file_system` application.
+
+  Two ways to customize the executable file path:
+
+    * Module config with `config.exs`:
+
+      ```elixir
+      config :file_system, :fs_mac,
+        executable_file: "YOUR_EXECUTABLE_FILE_PATH"`
+      ```
 
-    * config with `config.exs`
-      `config :file_system, :fs_mac, executable_file: "YOUR_EXECUTABLE_FILE_PATH"`
+    * System environment variable:
 
-    * config with `FILESYSTEM_FSMAC_EXECUTABLE_FILE` os environment
-      FILESYSTEM_FSMAC_EXECUTABLE_FILE=YOUR_EXECUTABLE_FILE_PATH
+      ```
+      export FILESYSTEM_FSMAC_EXECUTABLE_FILE="YOUR_EXECUTABLE_FILE_PATH"`
+      ```
   """
 
   use GenServer

lib/file_system/backends/fs_poll.ex

@@ -2,14 +2,13 @@ require Logger
 
 defmodule FileSystem.Backends.FSPoll do
   @moduledoc """
-  FileSysetm backend for any OS, a GenServer that regularly scans file system to
-  detect changes and send them to the worker process.
+  File system backend for any OS.
 
   ## Backend Options
 
     * `:interval` (integer, default: 1000), polling interval
 
-  ## Use FSPoll Backend
+  ## Using FSPoll Backend
 
   Unlike other backends, polling backend is never automatically chosen in any
   OS environment, despite being usable on all platforms.