2 files changed, 15 insertions, 7 deletions
diff --git a/en/devices/architecture/hidl/code-style.html b/en/devices/architecture/hidl/code-style.html
index 0746ff36..5f787d71 100644
--- a/en/devices/architecture/hidl/code-style.html
+++ b/en/devices/architecture/hidl/code-style.html
@@ -374,14 +374,21 @@ fine.</p>
   <li>TODOs</li>
   </ul>
 </li>
-<li>Use <code>/** */</code> mainly for Function documents/"docstrings" used for
-generated documentation. Example:
+<li>Use <code>/** */</code> for generated documentation. These can be applied
+only to type, method, field, and enum value declarations. Example:
 <pre class="prettyprint">
 /** Replied status */
-enum FooStatus {
-    OK            = 0, // no error
-    ERR_TRANSPORT = 1, // transport level error
-    ERR_ARG       = 2  // invalid args
+enum TeleportStatus {
+    /** Object entirely teleported. */
+    OK              = 0,
+    /** Methods return this if teleportation is not completed. */
+    ERROR_TELEPORT  = 1,
+    /**
+     * Teleportation could not be completed due to an object
+     * obstructing the path.
+     */
+    ERROR_OBJECT    = 2,
+    ...
 }
 </pre>
 <li>Multi-line comments should start a new line with <code>/**</code>, use
diff --git a/en/devices/architecture/hidl/index.html b/en/devices/architecture/hidl/index.html
index 5790b78c..35b166dd 100644
--- a/en/devices/architecture/hidl/index.html
+++ b/en/devices/architecture/hidl/index.html
@@ -135,7 +135,8 @@ of <code>=</code> and <code>|</code>) is part of the grammar.</p>
 <a href="code-style.html">Code Style Guide</a>.</p>
 
 <ul>
-<li><code>/** */</code> indicates a documentation comment.</li>
+<li><code>/** */</code> indicates a documentation comment. These can be applied
+only to type, method, field, and enum value declarations.</li>
 <li><code>/* */</code> indicates a multiline comment.</li>
 <li><code>//</code> indicates a comment to end of line. Aside from
 <code>//</code>, newlines are the same as any other whitespace. </li>