Further document annotations (#35)

- Document `@Arguments`
- Documents `@Discussion`
- Stub for `@Group`
- Partial document for `@Cli`
- Add terminology definitions to main page of user guide
- Slightly tweak some examples

guide/annotations/arguments.md

@@ -5,4 +5,43 @@ title: Arguments Annotation
 
 ## `@Arguments`
 
-The `@Arguments` annotation is applied to fields of a class to indicate that the field should be populated from any arguments that are not otherwise parsed as options.
+The `@Arguments` annotation is applied to fields of a class to indicate that the field should be populated from any string arguments that are not otherwise parsed as options.
+
+Arguments are typically used to take in free-form inputs such as lists of files to operate on.
+
+{% include alert.html %}
+By default if no field is annotated with `@Arguments` then it is illegal to pass in string arguments that are not options.
+
+### Simple Definition
+
+At its simplest the annotation requires no arguments and may be applied like so:
+
+```java
+@Arguments
+private List<String> files;
+```
+
+Here we define a field `files` which is a `List<String>` so each argument received will be treated as a `String` and the list populated appropriately.  Just like [`@Option`](option.html) the type of the arguments is inferred from the field to which the annotation applies, please see [Supported Types](../practise/types.html) for more detail on the types Airline supports.
+
+{% include alert.html %}
+If you do not explicitly instantiate collection arguments then they will be `null` if a user does not provide any appropriate arguments
+
+### Titles
+
+In more complex cases you may wish to have arguments where each argument denotes a different thing in which case you can use the `titles` field so set the titles of the arguments that will appear in [Help](../help/) e.g.
+
+```java
+@Arguments(title = { "host", "username" })
+private List<String> args;
+```
+
+Here we define a field `args` which again is a `List<String>` and with the titles `host` and `username`.  This will cause these titles to be displayed in help as opposed to the default title which is simply the name of the annotated field.
+
+### Description
+
+The `description` field may be used to describe how arguments are intended to be used e.g.
+
+```java
+@Arguments(description = "Provides the names of one/more files to process")
+private List<String> files;
+```

guide/annotations/cli.md

@@ -5,4 +5,32 @@ title: Cli Annotation
 
 ## `@Cli`
 
-The `@Cli` annotation is applied to a class to define a complex CLI consisting of potentially many commands.
+The `@Cli` annotation is applied to a class to define a complex CLI consisting of potentially many commands.
+
+At a minimum you need to define a name and at least one command for your CLI e.g.
+
+```java
+@Cli(name = "basic", 
+     defaultCommand = GettingStarted.class, 
+     commands = { GettingStarted.class, Tool.class })
+public class BasicCli { }
+```
+
+Here we define a CLI named `basic` that has a default command of `GettingStarted.class` which we saw on the introductory page of the [User Guide](../) and also contains the command `Tool.class` which we saw in the examples for the [`@Command`](command.html) annotation.
+
+{% include alert.html %}
+Names are restricted to not contain whitespace but otherwise can contain whatever characters you want.
+
+Remember that users need to be able to type the name at their command line terminal of choice so it is best to limit yourself to common characters i.e. alphanumerics and common punctuation marks.
+
+### Description
+
+As with commands typically we also want to add a `description` that describes what a CLI does e.g.
+
+```java
+@Cli(name = "basic", 
+    description = "Provides a basic example CLI",
+    defaultCommand = GettingStarted.class, 
+    commands = { GettingStarted.class, Tool.class })
+public class BasicCli {
+```

guide/annotations/command.md

@@ -11,7 +11,7 @@ The annotation is actually very simple, at a minimum it looks like the following
 
 ```java
 @Command(name = "tool")
-public class Tool {
+public class Tool { }
 ```
 
 Where the `name` field states the name of the command, this name is the name by which users will refer to the command and that will be displayed in [Help](../help/) for the command.
@@ -27,7 +27,7 @@ Generally you'll also want to add a `description` which gives users a brief over
 
 ```java
 @Command(name = "tool", description = "This tool does something interesting")
-public class Tool {
+public class Tool { }
 ```
 
 This is just a string that describes the functionality of your command, generally this should be kept relatively short.  If you want to include more detailed descriptions of functionality then you probably also want to use some of the [Help](../help/) annotations such as [`@Discussion`](discussion.html)
@@ -38,7 +38,7 @@ By default all commands in an Airline CLI are visible to users, however there ar
 
 ```java
 @Command(name = "tool", description = "This tool does something interesting", hidden = true)
-public class Tool {
+public class Tool { }
 ```
 
 When commands are hidden they will not be included in help (unless the help generator is explicitly specified to include them) so only users who are aware they are there can use them.
@@ -54,7 +54,7 @@ To specify which group(s) a command belongs to you use the `groupNames` fields l
 
 ```java
 @Command(name = "tool", description = "This tool does something interesting", hidden = true, groupNames = { "common", "foo bar"})
-public class Tool {
+public class Tool { }
 ```
 
 Here we add our command to the `common` group, we also add it to the `bar` group which is a sub-group of the `foo` group.

guide/annotations/discussion.md

@@ -5,4 +5,17 @@ title: Discussion Annotation
 
 ## `@Discussion`
 
-The `@Discussion` annotation may be applied to classes and provides a longer form discussion of a command that may be used for whatever purpose you desire.  This will be included in [Help](../help/) as an additional section.
+The `@Discussion` annotation may be applied to classes and provides a longer form discussion of a command that may be used for whatever purpose you desire.  This will be included in [Help](../help/) as an additional section.
+
+### Adding Discussion
+
+To add a discussion section simply add the `@Discussion` annotated to a class like so:
+
+```java
+@Discussion(paragraphs = {
+	"This is the first paragraph of discussion",
+	"In our second paragraph we go into much more depth",
+	"We can have as many paragraphs as we feel are necessary"})
+public class MyClass { }```
+
+The annotation takes a single `paragraphs` field which takes a `String[]` array where each entry in the array is treated as a separate paragraph.

guide/annotations/group.md

@@ -0,0 +1,8 @@
+---
+layout: page
+title: Group Annotation
+---
+
+## `@Group`
+
+The `@Group` annotation is used to specify group information.  This may be done as an alternative or in addition to using the relevant fields of the [`@Command`](command.html) or [`@Cli`](cli.html) annotations to specify groups.

guide/index.md

@@ -11,6 +11,23 @@ Welcome to the Airline Users Guide, this guide is intended to show you how to us
 
 All the examples contained in this user guide may be found in the repository on <a href="{{ site.github.repo }}/tree/master/airline-examples/src/main/java/com/github/rvesse/airline/examples/userguide">GitHub</a>
 
+## Definitions
+
+Before you get started reading this guide it is useful to introduce the terminology that Airline uses to make sure you are clear what we are referring to.
+
+- **Command Line Interface (CLI)**  
+  A Command Line Interface (CLI) is a collection of commands potentially grouped into hierarchical groupings.  `git` is a popular example of a CLI
+- **Command**  
+  A command is a single tool that is invoked by a user, a command may appear within multiple groups within a CLI and take a variety of options and arguments
+- **Command Group**  
+  A command group is a collection of commands within a CLI identified by a name.  Groups may themselves contain other groups to create hierarchies of commands. `git remote` is an example of a group within a CLI
+- **Option**  
+  An option is a combination of an identifying name e.g. `--name` followed by zero or more values that are used to populate a field of a command, for example `--name Example`
+- **Arguments**  
+  Arguments are any values passed to a command that are not otherwise interpreted i.e. they do not represent options, for example `Example`
+- **Restriction**  
+  A restriction is a constraint placed upon a CLI, options and/or arguments e.g. marking an option as required
+
 ## Getting Started
 
 ### Adding a Dependency