Continue documenting Maven plugin (#35, #45)

rvesse · Oct 31, 2018 · 0eda2ae · 0eda2ae
1 parent 1befad3
commit 0eda2ae
Show file tree

Hide file tree

Showing 2 changed files with 93 additions and 7 deletions.
diff --git a/airline-maven-plugin/src/main/java/com/github/rvesse/airline/maven/Mapping.java b/airline-maven-plugin/src/main/java/com/github/rvesse/airline/maven/Mapping.java
@@ -25,7 +25,7 @@ public class Mapping {
 
     /**
      * Constant used in a mapping to indicate that the default provider may be
-     * sued
+     * used
      */
     public static final String DEFAULT = "default";
 

diff --git a/docs/guide/practise/maven-plugin.md b/docs/guide/practise/maven-plugin.md
@@ -105,26 +105,50 @@ Each `<source>` element may also have an optional `<outputMode>` element and an
 
 The following configuration elements are supported by the plugin.  For each we note where they may be used, permitted child elements, example usage and descriptions of their functionality.
 
-### Top Level Elements
+### Top Level Elements
 
 These elements are all supplied directly as children of the plugin declarations `<configuration>` element.
 
 #### `<defaultOptions>`
 
 *Applicable Goals:* `airline:generate`
+*Child Elements*: `<columns>`, `<includeHidden>`, `<manSection>`, `<multiFile>` and `<properties>`
+
+Provides the default formatting options used to configure each requested output format.  These defaults can be overridden at both a `<format>` and `<source>` level.  See documentation for the child elements for their defaults.
+
+For example:
+
+```xml
+<defaultOptions>
+  <columns>120</columns>
+  <includeHidden>false</includeHidden>
+  <multiFile>true</multiFile>
+  <properties>
+    <key>value</key>
+  </properties>
+</defaultOptions>
+```
 
 #### `<failOnNoSources>`
 
 *Applicable Goals:* `airline:generate`, `airline:validate`
 
 Takes a Boolean value indicating whether the goal should fail the build if no sources are specified.  Defaults to **true**
 
+```xml
+<failOnNoSources>false</failOnNoSources>
+```
+
 #### `<failOnUnknownFormat>`
 
 *Applicable Goals:* `airline:generate`
 
 Takes a Boolean value indicating whether the goal should fail the build if a format is requested that is not either provided by Airline or registered via `<formatMappings>`.  Defaults to **true**
 
+```xml
+<failOnUnknownFormat>false</failOnUnknownFormat>
+```
+
 #### `<failOnUnsupportedOutputMode>`
 
 *Applicable Goals:* `airline:generate`
@@ -133,24 +157,56 @@ Takes a Boolean value indicating whether the goal should fail the build if an un
 
 When **false** an unsupported output mode simply results in a warning and help not being generated for some/all formats.
 
+```xml
+<failOnUnsupportedOutputMode>true</failOnUnsupportedOutputMode>
+```
+
 #### `<formatMappings>`
 
 *Applicable Goals:* `airline:generate`
+*Child Elements:* `<mapping>`
+
+Contains one or more `<mapping>` elements used to configure available output formats e.g.
+
+```xml
+<formatMappings>
+  <mapping>
+    <format>CUSTOM</format>
+    <provider>some.package.YourHelpProvider</provider>
+    <options>
+      <!-- Formatting options for this format -->
+    </options>
+  </mapping>
+</formatMappings>
+```
 
 #### `<formats>`
 
 *Applicable Goals:* `airline:generate`
+*Child Elements:* `<format>`
+
+Contains one or more `<format>` elements indicating desired output formats.  The separate `<formatMappings>` element is used to configure the available output formats e.g.
+
+```xml
+<formats>
+  <format>MAN</format>
+  <format>CLI</format>
+</formats>
+```
+
+If no formats are specified then `MAN` is the default.
 
 #### `<outputDirectory>`
 
 *Applicable Goals:* `airline:generate`
 
+Specifies the directory to which generated help output will be written.  Defaults to **${project.build.directory}/help/**
+
+
 ```xml
-<outputDirectory>${project.build.directory}/help/<outputDirectory>
+<outputDirectory>${project.build.directory}/man-pages/<outputDirectory>
 ```
 
-Specifies the directory to which generated help output will be written.  Defaults to **${project.build.directory}/help/**
-
 #### `<skipBadSources>`
 
 *Applicable Goals:* `airline:generate`
@@ -159,18 +215,49 @@ Takes a Boolean value indicating whether the goal should skip invalid sources.
 
 When **false** an invalid source will fail the build.
 
+```xml
+<skipBadSources>false</skipBadSources>
+```
+
 #### `<sources>`
 
-*Applicable Goals:* `airline:generate`, `airline:validate`
+*Applicable Goals:* `airline:generate`, `airline:validate`  
+*Child Elements:* `<source>`
+
+Specifies one or more `<source>` elements that specifies source(s) for which help should be generated e.g.
+
+```xml
+<sources>
+  <source>
+    <classes>
+      <class>some.package.YourCommand</class>
+    </classes>
+  </source>
+</sources>
+```
 
 ### Child Elements
 
 These elements are all supplied as child elements to the relevant top level elements.
 
 #### `<columns>`
 
+*Applicable Goals:* `airline:generate`  
+*Child Element Of:* `<defaultOptions>` and `<options>`
+
+Specifies the integer number of columns to use for column wrapped output formats e.g.
+
+```xml
+<columns>70</columns>
+```
+
 #### `<format>`
 
+*Applicable Goals:* `airline:generate`  
+*Child Element Of:* `<formats>` and `<mapping>`
+
+Specifies the name of an output format.  By default Airline recognizes the names `BASH`, `CLI`, `HTML`, `MAN` and `MARKDOWN` as referring to built in help formats.  However this mapping can be redefined by the `<formatMappings>` element as desired.
+
 #### `<includeHidden>`
 
 #### `<manSection>`
@@ -182,7 +269,6 @@ These elements are all supplied as child elements to the relevant top level elem
 #### `<outputMode>`
 
 *Child Element Of:* `<source>`
-*Permitted Child Elements:* **N/A**
 
 #### `<options>`