More new annotation docs (#73,#35)

- @positive and @Negative
- @ExactLength and @LengthRange
- Reorganise nav for restriction annotations to be clearer

docs/_includes/nav.html

@@ -57,32 +57,40 @@
                 </ul>
               </li>
               <li>
-              <a href="#">Value Restrictions</a>
+              <a href="#">General Value Restrictions</a>
                 <ul>
                   <li><a class="sidebar-nav-item" href="{{ site.baseurl }}/guide/annotations/allowed-raw-values.html">@AllowedRawValues</a></li>
                   <li><a class="sidebar-nav-item" href="{{ site.baseurl }}/guide/annotations/allowed-enum-values.html">@AllowedEnumValues</a></li>
                   <li><a class="sidebar-nav-item" href="{{ site.baseurl }}/guide/annotations/allowed-values.html">@AllowedValues</a></li>
-                  <li><a class="sidebar-nav-item" href="{{ site.baseurl }}/guide/annotations/max-length.html">@MaxLength</a></li>
-                  <li><a class="sidebar-nav-item" href="{{ site.baseurl }}/guide/annotations/min-length.html">@MinLength</a></li>
                   <li><a class="sidebar-nav-item" href="{{ site.baseurl }}/guide/annotations/not-blank.html">@NotBlank</a></li>
                   <li><a class="sidebar-nav-item" href="{{ site.baseurl }}/guide/annotations/not-empty.html">@NotEmpty</a></li>
-                  <li><a class="sidebar-nav-item" href="{{ site.baseurl }}/guide/annotations/pattern.html">@Pattern</a></li>
-                  <li><a class="sidebar-nav-item" href="{{ site.baseurl }}/guide/annotations/starts-with.html">@StartsWith</a></li>
-                  <li><a class="sidebar-nav-item" href="{{ site.baseurl }}/guide/annotations/ends-with.html">@EndsWith</a></li>
                   <li><a class="sidebar-nav-item" href="{{ site.baseurl }}/guide/annotations/path.html">@Path, @File and @Directory</a></li>
                   <li><a class="sidebar-nav-item" href="{{ site.baseurl }}/guide/annotations/port.html">@Port and @PortRange</a></li>
                 </ul>
               </li>
               <li>
-              <a href="#">Value Range Restrictions</a>
+              <a href="#">Numeric Value Restrictions</a>
                 <ul>
                   <li><a class="sidebar-nav-item" href="{{ site.baseurl }}/guide/annotations/byte-range.html">@ByteRange</a></li>
                   <li><a class="sidebar-nav-item" href="{{ site.baseurl }}/guide/annotations/double-range.html">@DoubleRange</a></li>
                   <li><a class="sidebar-nav-item" href="{{ site.baseurl }}/guide/annotations/float-range.html">@FloatRange</a></li>
                   <li><a class="sidebar-nav-item" href="{{ site.baseurl }}/guide/annotations/integer-range.html">@IntegerRange</a></li>
-                  <li><a class="sidebar-nav-item" href="{{ site.baseurl }}/guide/annotations/lexical-range.html">@LexicalRange</a></li>
                   <li><a class="sidebar-nav-item" href="{{ site.baseurl }}/guide/annotations/long-range.html">@LongRange</a></li>
                   <li><a class="sidebar-nav-item" href="{{ site.baseurl }}/guide/annotations/short-range.html">@ShortRange</a></li>
+                  <li><a class="sidebar-nav-item" href="{{ site.baseurl }}/guide/annotations/pos-neg.html">@Positive and @Negative</a></li>
+                </ul>
+              </li>
+              <li>
+              <a href="#">String Value Restrictions</a>
+                <ul>
+                  <li><a class="sidebar-nav-item" href="{{ site.baseurl }}/guide/annotations/starts-with.html">@StartsWith</a></li>
+                  <li><a class="sidebar-nav-item" href="{{ site.baseurl }}/guide/annotations/ends-with.html">@EndsWith</a></li>
+                  <li><a class="sidebar-nav-item" href="{{ site.baseurl }}/guide/annotations/pattern.html">@Pattern</a></li>
+                  <li><a class="sidebar-nav-item" href="{{ site.baseurl }}/guide/annotations/max-length.html">@MaxLength</a></li>
+                  <li><a class="sidebar-nav-item" href="{{ site.baseurl }}/guide/annotations/min-length.html">@MinLength</a></li>
+                  <li><a class="sidebar-nav-item" href="{{ site.baseurl }}/guide/annotations/exact-length.html">@ExactLength</a></li>
+                  <li><a class="sidebar-nav-item" href="{{ site.baseurl }}/guide/annotations/length-range.html">@LengthRange</a></li>
+                  <li><a class="sidebar-nav-item" href="{{ site.baseurl }}/guide/annotations/lexical-range.html">@LexicalRange</a></li>
                 </ul>
               </li>
             </ul>

docs/guide/annotations/exact-length.md

@@ -0,0 +1,20 @@
+---
+layout: page
+title: ExactLength Annotation
+---
+
+## `@ExactLength`
+
+The `@ExactLength` annotation may be applied to fields annotated with [`@Option`](option.html) and [`@Arguments`](arguments.html) to limit the length of the value provided to a specific length e.g.
+
+```java
+@Option(name = "--reference", arity = 1)
+@MaxLength(length = 10)
+private String reference;
+```
+
+Restricts the `--reference` option to values of exactly 10 characters.
+
+### Related Annotations
+
+If you want to restrict the minimum/maximum length of a value then use the [`@MinLength`](min-length.html) or [`@MaxLength`](max-length) annotations.

docs/guide/annotations/length-range.md

@@ -0,0 +1,19 @@
+---
+layout: page
+title: LengthRange Annotation
+---
+
+## `@LengthRange`
+
+The `@LengthRange` annotation may be applied to fields annotated with [`@Option`](option.html) and [`@Arguments`](arguments.html) to limit the length of values that an option may be used with to a range of lengths e.g.
+
+```java
+@Option(name = "--reference", arity = 1)
+@LengthRange(min = 5, max = 10)
+private String reference;
+```
+This specifies that the `--reference` option only allows values with lengths of 5 to 10 characters to be specified by the user.  Any other length value will be rejected.
+
+### Related Annotations
+
+If you have an exact length to enforce then you should use the [`@ExactLength`](exact-length.html) annotation.  If you want to restrict just the minimum/maximum length of a value then use the [`@MinLength`](min-length.html) or [`@MaxLength`](max-length) annotations.

docs/guide/annotations/max-length.md

@@ -17,4 +17,4 @@ Restricts the `--reference` option to values of at most 10 characters.
 
 ### Related Annotations
 
-If you want to restrict the minimum length of a value then use the [`@MinLength`](min-length.html) annotation.
+If you want to restrict the minimum length of a value then use the [`@MinLength`](min-length.html) annotation.  For exact length restrictions use the [`@ExactLength`](exact-length.html) annotation.

docs/guide/annotations/min-length.md

@@ -17,4 +17,4 @@ Restricts the `--reference` option to values of at least 5 characters.
 
 ### Related Annotations
 
-If you want to restrict the minimum length of a value then use the [`@MaxLength`](max-length.html) annotation.
+If you want to restrict the minimum length of a value then use the [`@MaxLength`](max-length.html) annotation.  For exact length restrictions use the [`@ExactLength`](exact-length.html) annotation.

docs/guide/annotations/pos-neg.md

@@ -0,0 +1,54 @@
+---
+layout: page
+title: Positive and Negative Annotations
+---
+
+## `@Positive`
+
+The `@Positive` annotation is applied to numerically typed fields to indicate that their values must be a positive number e.g.
+
+```java
+@Option(name = "-i", title = "Integer", arity = 1)
+@Positive
+public long i;
+```
+
+Here the `-i` option must take a positive value.
+
+### Treatment of Zero
+
+By default zero is considered a positive number, if you do not want this to be the case you can add `includesZero = false` to your annotation e.g.
+
+```java
+@Option(name = "-i", title = "Integer", arity = 1)
+@Positive(includesZero = false)
+public long i;
+```
+
+## `@Negative`
+
+`@Negative` is the opposite of `@Positive`, it is applied to numeric fields to indicate that their values must be a negative number e.g.
+
+```java
+@Option(name = "-i", title = "Integer", arity = 1)
+@Negative
+public long i;
+```
+
+Here the `-i` option must take a negative value.
+
+### Treatment of Zero
+
+By default zero is considered a positive number, if you want to treat it as a negative number you can add `includesZero = true` to your annotation e.g.
+
+```java
+@Option(name = "-i", title = "Integer", arity = 1)
+@Negative(includesZero = true)
+public long i;
+```
+
+### Related Annotations
+
+For more specific value ranges on numeric fields use the various numeric range annotations - [`@ByteRange`](byte-range.html), [`@ShortRange`](short-range.html), [`@IntegerRange`](integer-range.html), [`@LongRange`](long-range.html), [`@FloatRange`](float-range.html) and [`@DoubleRange`](double-range.html) - to specify desired minimum and maximum values.
+
+For limiting numeric fields to small sets of values consider the [`@AllowedValues`](allowed-values.html) annotation.