Update gen_aidl documentation to be more clear

Summary:
This fixes #103
Closes #1120

Test Plan: Loaded http://localhost:9811/rule/gen_aidl.html

Reviewed By: JoelMarcey, sdwilsh

fbshipit-source-id: 43ced15

docs/__common.soy

@@ -1139,6 +1139,11 @@ docsearch({
 {call .cmd_link}{param name : 'project' /}{/call}
 {/template}
 
+/***/
+{template .cmd_root}
+{call .cmd_link}{param name : 'root' /}{/call}
+{/template}
+
 /***/
 {template .cmd_run}
 {call .cmd_link}{param name : 'run' /}{/call}

docs/rule/gen_aidl.soy

@@ -38,11 +38,13 @@ from <code>.aidl</code> files.
 {call buck.arg}
   {param name: 'import_path' /}
   {param desc}
-  The search path for import statements for the aidl command. 
-  (This is the <code>-I</code> argument when invoking aidl 
-  from the command line. For many apps it will be the base dir where all 
-  aidl files are, with project root as its parent, 
-  e.g. <code>app/src/main/aidl</code>. )
+  The search path for import statements for the aidl command.
+  (This is the <code>-I</code> argument when invoking aidl
+  from the command line. For many apps it will be the base dir where all
+  aidl files are, with project root as its parent,
+  e.g. <code>app/src/main/aidl</code>.).  This is the same as the path to the
+  {sp}<code>aidl</code> file relative to what would be returned from{sp}
+  {call buck.cmd_root /}.
   {/param}
 {/call}
 
@@ -56,6 +58,27 @@ from <code>.aidl</code> files.
 
 {/param} // close args
 
+{param examples}
+{literal}<pre class="prettyprint lang-py">
+android_library(
+  name = 'lib',
+  srcs = glob(['**/*.java']) + [':aidl'],
+  manifest = '//res/org/opencv:manifest',
+  deps = [
+    '//res/org/opencv:res',
+  ],
+  visibility = [ 'PUBLIC' ],
+)
+
+gen_aidl(
+    name = 'aidl',
+    aidl = 'engine/OpenCVEngineInterface.aidl',
+    import_path = 'java/',
+)
+</pre>
+{/literal}
+{/param} // close examples
+
 {/call} // close buck.rule
 
     {/param}