Added a user guide based on MkDocs

doc/usage.md

@@ -0,0 +1,82 @@
+path: src/branch/master
+source: lib/EnumTrait.php
+# Usage
+
+## Create the enumeration
+Just use the `Enum\EnumTrait` trait on a class:
+
+```php
+<?php
+use Enum\{EnumTrait};
+
+/**
+ * Specifies the day of the week.
+ */
+final class DayOfWeek {
+  use EnumTrait;
+
+  const SUNDAY = 0;
+  const MONDAY = 1;
+  const TUESDAY = 2;
+  const WEDNESDAY = 3;
+  const THURSDAY = 4;
+  const FRIDAY = 5;
+  const SATURDAY = 6;
+}
+```
+
+This trait adds a private constructor to the enumerated type: it prohibits its instantiation.
+
+Thus, the obtained enumeration can only contain static members.
+You should only use [scalar constants](https://secure.php.net/manual/en/function.is-scalar.php), and possibly methods.
+
+## Work with the enumeration
+Check whether a value is defined among the enumerated type:
+
+```php
+<?php
+DayOfWeek::isDefined(DayOfWeek::SUNDAY); // true
+DayOfWeek::isDefined('foo'); // false
+```
+
+Ensure that a value is defined among the enumerated type:
+
+```php
+<?php
+DayOfWeek::assert(DayOfWeek::MONDAY); // DayOfWeek::MONDAY
+DayOfWeek::assert('foo'); // (throws \UnexpectedValueException)
+
+DayOfWeek::coerce(DayOfWeek::MONDAY); // DayOfWeek::MONDAY
+DayOfWeek::coerce('bar'); // null
+DayOfWeek::coerce('baz', DayOfWeek::TUESDAY); // DayOfWeek::TUESDAY
+```
+
+Get the zero-based position of a value in the enumerated type declaration:
+
+```php
+<?php
+DayOfWeek::getIndex(DayOfWeek::WEDNESDAY); // 3
+DayOfWeek::getIndex('foo'); // -1
+```
+
+Get the name associated to an enumerated value:
+
+```php
+<?php
+DayOfWeek::getName(DayOfWeek::THURSDAY); // "THURSDAY"
+DayOfWeek::getName('foo'); // "" (empty)
+```
+
+Get information about the enumerated type:
+
+```php
+<?php
+DayOfWeek::getEntries();
+// ["SUNDAY" => 0, "MONDAY" => 1, "TUESDAY" => 2, "WEDNESDAY" => 3, "THURSDAY" => 4, "FRIDAY" => 5, "SATURDAY" => 6]
+
+DayOfWeek::getNames();
+// ["SUNDAY", "MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY", "SATURDAY"]
+
+DayOfWeek::getValues();
+// [0, 1, 2, 3, 4, 5, 6]
+```