Documentation for some restriction annotations (#35)

- Document various requirement annotations
- Links for occurrences annotations
- Partially document @unrestricted annotation

_includes/head.html

@@ -23,4 +23,8 @@
   <!-- Icons -->
   <link rel="apple-touch-icon-precomposed" sizes="144x144" href="{{ site.baseurl }}/public/apple-touch-icon-144-precomposed.png">
   <link rel="shortcut icon" href="{{ site.baseurl }}/public/favicon.ico">
+
+  <!-- Scripts -->
+  <script src="{{ site.baseurl }}/public/js/jquery.js" type="text/javascript"></script>
+  </script>
 </head>

_includes/nav.html

@@ -18,6 +18,11 @@
   	  	  <li><a class="sidebar-nav-item" href="{{ site.baseurl }}/guide/annotations/hide-section.html">@HideSection</a></li>
   	  	  <li><a class="sidebar-nav-item" href="{{ site.baseurl }}/guide/annotations/license.html">@License</a></li>
   	  	  <li><a class="sidebar-nav-item" href="{{ site.baseurl }}/guide/annotations/prose-section.html">@ProseSection</a></li>
+               <hr />
+               <li><a class="sidebar-nav-item" href="{{ site.baseurl }}/guide/annotations/required.html">@Required</a></li>
+               <li><a class="sidebar-nav-item" href="{{ site.baseurl }}/guide/annotations/require-some.html">@RequireSome</a></li>
+               <li><a class="sidebar-nav-item" href="{{ site.baseurl }}/guide/annotations/require-only-one.html">@RequireOnlyOne</a></li>
+               <li><a class="sidebar-nav-item" href="{{ site.baseurl }}/guide/annotations/mutually-exclusive-with.html">@MutuallyExclusiveWith</a></li>
              </ol>
   	  </li>
   	  <li>

_includes/sidebar.html

@@ -9,7 +9,7 @@ <h1>
       <p class="lead">{{ site.description }}</p>
     </div>
 
-    <nav class="sidebar-nav">
+    <nav class="sidebar-nav" id="menu">
 
     {% include nav.html context=page.url %}
 

_includes/toc.html

@@ -1,6 +1,5 @@
 <div id="toc"></div>
 
-<script src="{{ site.baseurl }}/public/js/jquery.js" type="text/javascript"></script>
 <script src="{{ site.baseurl }}/public/js/toc.js" type="text/javascript"></script>	<script type="text/javascript">
 $(document).ready(function() {
     $('#toc').toc();

guide/annotations/index.md

@@ -23,10 +23,24 @@ The following annotations are used to define the high level aspects of your CLIs
 
 The following annotations are used to define various restrictions on options and arguments that cause Airline to automatically enforce restrictions on their usage e.g. requiring an option take a value from a restricted set of values.
 
-**TODO** - List restriction annotations
+All these annotations are applied to fields that are annotated with [`@Option`](option.html) or [`@Arguments`](arguments.html) and are automatically discovered during meta-data extraction.  If you are overriding the definition of an option then restrictions are automatically inherited unless you specify new restrictions further as part of your override.  In the case where you wish to remove inherited restrictions you can use the special [`@Unrestricted`](unrestricted.html) annotation to indicate that.
 
-- Requirement related annotations:
-    - The [`@Required`](required.html) annotation indicates that an option/argument must be specified
+### Requirement Restrictions
+
+The following annotations are used to specify that options/arguments (or combinations thereof) are required:
+
+- The [`@Required`](required.html) annotation indicates that an option/argument must be specified
+- The [`@RequireSome`](require-some.html) annotation indicates that one/more from some set of options must be specified
+- The [`@RequireOnlyOne`](require-only-one.html) annotation indicates that precisely one of some set of options must be specified
+- The [`@MutuallyExclusiveWith`](mutually-exclusive-with.html) annotation indicates that precisely one of some set of options may be specified
+
+### Occurence Restrictions
+
+The following annotations are used to specify the number of times that options/arguments can be specified:
+
+- The [`@Once`](once.html) annotation indicates that at option/argument may be specified only once
+- The [`@MinOccurrences`](min-occurrences.html) annotation indicates that an option/argument must be specified a minimum number of times
+- The [`@MaxOccurrences`](max-occurrences.html) annotation indicates that an option/argument may be specified a maximum number of times
 
 ## Help Annotations
 

guide/annotations/mutually-exclusive-with.md

@@ -0,0 +1,31 @@
+---
+layout: page
+title: MutuallyExclusiveWith Annotation
+---
+
+## `@MutuallyExclusiveWith`
+
+The `@MutuallyExclusiveWith` annotation is applied to a field annotated with [`@Option`](option.html) to indicate that exactly one from some set of options may be specified e.g.
+
+```java
+@Option(name = "--num", 
+        arity = 1, 
+        title = "Number")
+@MutuallyExclusiveWith(tag = "identifier")
+private int number;
+
+@Option(name = "--name",
+        arity = 1,
+        title = "Name")
+@MutuallyExclusiveWith(tag = "identifier")
+```
+
+When fields are marked with `@MutuallyExclusiveWith` if the user specifies more than one of the options that have the same `tag` value then an error will be thrown during [parsing](../parser/).
+
+In this example the user may specify exactly one of the `--num` or `--name` option or they may specify neither. If they specify both then it is treated as an error.
+
+### Related Annotations
+
+If you want to require that at least one of some set of options be specified then you should use [`@RequireSome`](require-some.html) instead.
+
+If you want to require exactly one from some set of options then you should use [`@RequireOnlyOne`](require-only-one.html).

guide/annotations/require-only-one.md

@@ -0,0 +1,31 @@
+---
+layout: page
+title: RequireOnlyOne Annotation
+---
+
+## `@RequireOnlyOne`
+
+The `@RequireOnlyOne` annotation is applied to a field annotated with [`@Option`](option.html) to indicate that exactly one from some set of options must be specified e.g.
+
+```java
+@Option(name = "--num", 
+        arity = 1, 
+        title = "Number")
+@RequireOnlyOne(tag = "identifier")
+private int number;
+
+@Option(name = "--name",
+        arity = 1,
+        title = "Name")
+@RequireOnlyOne(tag = "identifier")
+```
+
+When fields are marked with `@RequireOnlyOne` if the user fails to supply exactly one of the options that have the same `tag` value then an error will be thrown during [parsing](../parser/).
+
+In this example the user must specify exactly one of the `--num` or `--name` option, if they specify neither or specify both then it is treated as an error.
+
+### Related Annotations
+
+If you want to require that at least one of some set of options be specified then you should use [`@RequireSome`](require-some.html) instead.
+
+If you optionally want to allow only one from some set of options then you should use [`@MutuallyExclusiveWith`](mutually-exclusive-with.html).

guide/annotations/require-some.md

@@ -0,0 +1,31 @@
+---
+layout: page
+title: RequireSome Annotation
+---
+
+## `@RequireSome`
+
+The `@RequireSome` annotation is applied to a field annotated with [`@Option`](option.html) to indicate that at least one from some set of options must be specified e.g.
+
+```java
+@Option(name = "--num", 
+        arity = 1, 
+        title = "Number")
+@RequireSome(tag = "identifier")
+private int number;
+
+@Option(name = "--name",
+        arity = 1,
+        title = "Name")
+@RequireSome(tag = "identifier")
+```
+
+When fields are marked with `@RequireSome` if the user fails to supply at least one of the options that have the same `tag` value then an error will be thrown during [parsing](../parser/).
+
+In this example the user must specify at least one of the `--num` or `--name` option and may specify both if desired.
+
+### Related Annotations
+
+If you want to require that at most one of some set of options be specified then you should use [`@RequireOnlyOne`](require-only-one.html) instead.
+
+If you optionally want to allow only one from some set of options then you should use [`@MutuallyExclusiveWith`](mutually-exclusive-with.html).

guide/annotations/required.md

@@ -15,4 +15,8 @@ The `@Required` annotation is applied to a field annotated with [`@Option`](opti
 private int number;
 ```
 
-When a field is marked with `@Required` if the user fails to supply that option/argument then an error will be thrown during [parsing](../parser/)
+When a field is marked with `@Required` if the user fails to supply that option/argument then an error will be thrown during [parsing](../parser/)
+
+### Related Annotations
+
+If you want to require one option from some set of options then you should use [`@RequireSome`](require-some.md)

guide/annotations/unrestricted.md

@@ -0,0 +1,11 @@
+---
+layout: page
+title: Unrestricted Annotation
+---
+
+## `@Unrestricted`
+
+The `@Unrestricted` annotation is applied to fields annotated with [`@Option`](option.html) or [`@Arguments`](arguments.html) to indicate that no restrictions should apply.
+
+This is useful because by default restrictions are inherited so if you wish to remove restrictions when overriding an option definition then you need to use this annotation.
+