Added javadocs.

Renamed intent remove command.

@@ -10,9 +10,9 @@ import org.onlab.onos.net.intent.IntentService;
 /**
  * Removes host-to-host connectivity intent.
  */
-@Command(scope = "onos", name = "remove-host-intent",
-         description = "Removes host-to-host connectivity intent")
-public class RemoveHostToHostIntentCommand extends AbstractShellCommand {
+@Command(scope = "onos", name = "remove-intent",
+         description = "Removes the specified intent")
+public class IntentRemoveCommand extends AbstractShellCommand {
 
     @Argument(index = 0, name = "id", description = "Intent ID",
               required = true, multiValued = false)

@@ -64,15 +64,15 @@
             <action class="org.onlab.onos.cli.net.IntentsListCommand"/>
         </command>
         <command>
-            <action class="org.onlab.onos.cli.net.AddHostToHostIntentCommand"/>
+            <action class="org.onlab.onos.cli.net.IntentRemoveCommand"/>
             <completers>
-                <ref component-id="hostIdCompleter"/>
+                <ref component-id="intentIdCompleter"/>
             </completers>
         </command>
         <command>
-            <action class="org.onlab.onos.cli.net.RemoveHostToHostIntentCommand"/>
+            <action class="org.onlab.onos.cli.net.AddHostToHostIntentCommand"/>
             <completers>
-                <ref component-id="intentIdCompleter"/>
+                <ref component-id="hostIdCompleter"/>
             </completers>
         </command>
 

@@ -4,5 +4,53 @@
  * <em>what</em> rather than the <em>how</em>. This makes such instructions
  * largely independent of topology and device specifics, thus allowing them to
  * survive topology mutations.
+ * <p/>
+ * The controller core provides a suite of built-in intents and their compilers
+ * and installers. However, the intent framework is extensible in that it allows
+ * additional intents and their compilers or installers to be added
+ * dynamically at run-time. This allows others to enhance the initial arsenal of
+ * connectivity and policy-based intents available in base controller software.
+ * <p/>
+ * The following diagram depicts the state transition diagram for each top-level intent:<br>
+ * <img src="doc-files/intent-states.png" alt="ONOS intent states">
+ * <p/>
+ * The controller core accepts the intent specifications and translates them, via a
+ * process referred to as intent compilation, to installable intents, which are
+ * essentially actionable operations on the network environment.
+ * These actions are carried out by intent installation process, which results
+ * in some changes to the environment, e.g. tunnel links being provisioned,
+ * flow rules being installed on the data-plane, optical lambdas being reserved.
+ * <p/>
+ * After an intent is submitted by an application, it will be sent immediately
+ * (but asynchronously) into a compiling phase, then to installing phase and if
+ * all goes according to plan into installed state. Once an application decides
+ * it no longer wishes the intent to hold, it can withdraw it. This describes
+ * the nominal flow. However, it may happen that some issue is encountered.
+ * For example, an application may ask for an objective that is not currently
+ * achievable, e.g. connectivity across to unconnected network segments.
+ * If this is the case, the compiling phase may fail to produce a set of
+ * installable intents and instead result in a failed compile. If this occurs,
+ * only a change in the environment can trigger a transition back to the
+ * compiling state.
+ * <p/>
+ * Similarly, an issue may be encountered during the installation phase in
+ * which case the framework will attempt to recompile the intent to see if an
+ * alternate approach is available. If so, the intent will be sent back to
+ * installing phase. Otherwise, it will be parked in the failed state. Another
+ * scenario that’s very likely to be encountered is where the intent is
+ * successfully compiled and installed, but due to some topology event, such
+ * as a downed or downgraded link, loss of throughput may occur or connectivity
+ * may be lost altogether, thus impacting the viability of a previously
+ * satisfied intent. If this occurs, the framework will attempt to recompile
+ * the intent, and if an alternate approach is available, its installation
+ * will be attempted. Otherwise, the original top-level intent will be parked
+ * in the failed state.
+ * <p/>
+ * Please note that all *ing states, depicted in orange, are transitional and
+ * are expected to last only a brief amount of time. The rest of the states
+ * are parking states where the intent may spent some time; except for the
+ * submitted state of course. There, the intent may pause, but only briefly,
+ * while the system determines where to perform the compilation or while it
+ * performs global recomputation/optimization across all prior intents.
  */
 package org.onlab.onos.net.intent;
\ No newline at end of file