Improve Documentation (#24)

CHANGELOG.md

@@ -0,0 +1,9 @@
+# CHANGELOG
+
+## v1
+
+ * Removed Helper Functions in Module `Crontab`
+ * Moved `get_[next|previous]_run_dates` to `Crontab.Scheduler`
+ * Renamed Modules to a better name
+ * Introduction of `~e[CRON_EXPRESSION]` sigil
+ * Renamed function to conventions. (`?` for booleans, `!` for functions that raise errors)

README.md

@@ -26,96 +26,6 @@ Parse Cron Format Strings, Write Cron Format Strings and Caluclate Execution Dat
     end
     ```
 
-## [Documentation](https://hexdocs.pm/crontab/)
-
 ## Usage
 
-### Helper Functions
-
-```elixir
-iex> Crontab.get_next_run_date("* * * * *")
-{:ok, ~N[2016-12-23 16:00:00.348751]}
-
-iex> Crontab.get_next_run_date("* * * * *", ~N[2016-12-17 00:00:00])
-{:ok, ~N[2016-12-17 00:00:00]}
-
-iex> Crontab.get_next_run_dates(3, "* * * * *")
-[{:ok, ~N[2016-12-23 16:00:00]},
- {:ok, ~N[2016-12-23 16:01:00]},
- {:ok, ~N[2016-12-23 16:02:00]}]
-
-iex> Crontab.get_next_run_dates(3, "* * * * *", ~N[2016-12-17 00:00:00])
-[{:ok, ~N[2016-12-17 00:00:00]},
- {:ok, ~N[2016-12-17 00:01:00]},
- {:ok, ~N[2016-12-17 00:02:00]}]
-
-iex> Crontab.get_previous_run_date("* * * * *")
-{:ok, ~N[2016-12-23 16:00:00.348751]}
-
-iex> Crontab.get_previous_run_date("* * * * *", ~N[2016-12-17 00:00:00])
-{:ok, ~N[2016-12-17 00:00:00]}
-
-iex> Crontab.get_previous_run_dates(3, "* * * * *")
-[{:ok, ~N[2016-12-23 16:00:00]},
- {:ok, ~N[2016-12-23 15:59:00]},
- {:ok, ~N[2016-12-23 15:58:00]}]
-
-iex> Crontab.get_previous_run_dates(3, "* * * * *", ~N[2016-12-17 00:00:00])
-[{:ok, ~N[2016-12-17 00:00:00]},
- {:ok, ~N[2016-12-16 23:59:00]},
- {:ok, ~N[2016-12-16 23:58:00]}]
-
-iex> Crontab.matches_date?("*/2 * * * *")
-{:ok, true}
-
-iex> Crontab.matches_date?("*/7 * * * *")
-{:ok, false}
-
-iex> Crontab.matches_date?("*/2 * * * *", ~N[2016-12-17 00:02:00])
-{:ok, true}
-
-iex> Crontab.matches_date?("*/7 * * * *", ~N[2016-12-17 00:06:00])
-{:ok, false}
-```
-
-### Parse Cron Format Strings
-```elixir
-iex> Crontab.CronExpression.Parser.parse "* * * * *"
-{:ok,
-  %Crontab.CronExpression{day: [:*], hour: [:*], minute: [:*],
-  month: [:*], weekday: [:*], year: [:*]}}
-iex> Crontab.CronExpression.Parser.parse "fooo"
-{:error, "Can't parse fooo as interval minute."}
-```
-
-### Write Cron Format Strings
-```elixir
-iex> Crontab.CronExpression.Composer.compose %Crontab.CronExpression{}
-"* * * * * *"
-iex> Crontab.CronExpression.Composer.compose %Crontab.CronExpression{minute: [9, {:-, 4, 6}, {:/, :*, 9}]}
-"9,4-6,*/9 * * * * *"
-```
-
-### Check if Cron Interval matches Date
-```elixir
-iex> Crontab.DateChecker.matches_date? :hour, [{:"/", 4}, 7], ~N[2004-04-16 04:07:08]
-true
-
-iex> Crontab.DateChecker.matches_date? :hour, [8], ~N[2004-04-16 04:07:08]
-false
-
-iex> Crontab.DateChecker.matches_date? %Crontab.CronExpression{minute: [{:"/", 8}]}, ~N[2004-04-16 04:08:08]
-true
-
-iex> Crontab.DateChecker.matches_date? %Crontab.CronExpression{minute: [{:"/", 9}]}, ~N[2004-04-16 04:07:08]
-false
-```
-
-### Get next Running Day for Cron interval
-```elixir
-iex> Crontab.Scheduler.get_next_run_date(%Crontab.CronExpression{}, ~N[2002-01-13 23:00:07])
-{:ok, ~N[2002-01-13 23:00:00]}
-
-iex> Crontab.Scheduler.get_next_run_date(%Crontab.CronExpression{year: [{:/, :*, 9}]}, ~N[2002-01-13 23:00:07])
-{:ok, ~N[2007-01-01 00:00:00]}
-```
+Please look into the [Documentation](https://hexdocs.pm/crontab/) for usage examples.

docs/Getting Started.md

@@ -0,0 +1 @@
+# Usage Examples

lib/crontab/date_checker.ex

@@ -33,6 +33,7 @@ defmodule Crontab.DateChecker do
       true
   """
   @spec matches_date?(CronExpression.condition_list, NaiveDateTime.t) :: boolean
+  def matches_date?(condition_list, date)
   def matches_date?([], _), do: true
   def matches_date?([{interval, conditions} | tail], execution_date) do
     matches_date?(interval, conditions, execution_date) && matches_date?(tail, execution_date)

mix.exs

@@ -1,15 +1,18 @@
 defmodule Crontab.Mixfile do
   use Mix.Project
 
+  @version "0.8.5"
+
   def project do
     [app: :crontab,
-     version: "0.8.5",
+     version: @version,
      elixir: "~> 1.3",
      build_embedded: Mix.env == :prod,
      start_permanent: Mix.env == :prod,
      description: description(),
      package: package(),
      deps: deps(),
+     docs: docs(),
      test_coverage: [tool: ExCoveralls]]
   end
 
@@ -52,4 +55,15 @@ defmodule Crontab.Mixfile do
      licenses: ["MIT"],
      links: %{"GitHub" => "https://github.com/jshmrtn/crontab"}]
   end
+
+  defp docs do
+    [main: "getting-started",
+     source_ref: "v" <> @version,
+     source_url: "https://github.com/jshmrtn/crontab",
+     extras: [
+       "pages/Getting Started.md",
+       "CHANGELOG.md",
+       "pages/Basic Usage.md"
+    ]]
+  end
 end

pages/Basic Usage.md

@@ -0,0 +1,66 @@
+# Basic Usage
+
+## Extended Cron expressions
+
+An extended cron expression has more precision then a normal cron expression. It also specifies the second.
+
+If you want to use extended cron expressions with the sigil, just append an `e`.
+
+## Checking if a Cron Expression Matches a date
+
+```elixir
+iex> import Crontab.CronExpression
+iex> Crontab.DateChecker.matches_date?(~e[*/2], ~N[2017-01-01 01:01:00])
+false
+iex> Crontab.DateChecker.matches_date?(~e[*], ~N[2017-01-01 01:01:00])
+true
+```
+
+## Find Next / Previous Execution Date candidates
+
+All the date parameters default to now.
+
+For previous, just replace `next` in the code below.
+
+```elixir
+iex> import Crontab.CronExpression
+iex> Crontab.Scheduler.get_next_run_date(~e[*/2], ~N[2017-01-01 01:01:00])
+{:ok, ~N[2017-01-01 01:02:00]}
+iex> Crontab.Scheduler.get_next_run_date!(~e[*/2], ~N[2017-01-01 01:01:00])
+{:ok, ~N[2017-01-01 01:02:00]}
+```
+
+```elixir
+iex> Crontab.Scheduler.get_next_run_dates(3, ~e[*/2], ~N[2017-01-01 01:01:00])
+{:ok,
+ [~N[2017-01-01 01:02:00], ~N[2017-01-01 01:04:00], ~N[2017-01-01 01:06:00]]}
+iex> Crontab.Scheduler.get_next_run_dates!(3, ~e[*/2], ~N[2017-01-01 01:01:00])
+[~N[2017-01-01 01:02:00], ~N[2017-01-01 01:04:00], ~N[2017-01-01 01:06:00]]
+```
+
+## Parse Cron Expressions
+
+If you statically define cron expressions, use the `~e[cron expression]` sigil.
+
+For dynamic cron expressions, there is a Parser module.
+
+The parser module takes an optional `extended` flag. This is to mark if the expression contains seconds.
+This defaults to `false`.
+
+```elixir
+iex> Crontab.CronExpression.Parser.parse "* * * * *"
+{:ok,
+  %Crontab.CronExpression{day: [:*], hour: [:*], minute: [:*],
+  month: [:*], weekday: [:*], year: [:*]}}
+iex> Crontab.CronExpression.Parser.parse! "* * * * *"
+%Crontab.CronExpression{day: [:*], hour: [:*], minute: [:*],
+ month: [:*], weekday: [:*], year: [:*]}
+```
+
+## Compose Cron expressions
+```elixir
+iex> Crontab.CronExpression.Composer.compose %Crontab.CronExpression{}
+"* * * * * *"
+iex> Crontab.CronExpression.Composer.compose %Crontab.CronExpression{minute: [9, {:-, 4, 6}, {:/, :*, 9}]}
+"9,4-6,*/9 * * * * *"
+```

pages/Getting Started.md

@@ -0,0 +1,25 @@
+# Getting Started
+## Installation
+
+  1. Add `crontab` to your list of dependencies in `mix.exs`:
+
+    ```elixir
+    def deps do
+      [{:crontab, "~> 0.8.5"}]
+    end
+    ```
+
+  2. Ensure `crontab` is started before your application:
+
+    ```elixir
+    def application do
+      [applications: [:crontab]]
+    end
+    ```
+
+## Import cron expression sigil
+Everywhere you want to use the cron expression sigil (`e[cron expression]`), import `Crontab.CronExpression`.
+
+```elixir
+import Crontab.CronExpression
+```