diff --git a/drm/crypto/1.0/ICryptoFactory.hal b/drm/crypto/1.0/ICryptoFactory.hal
index 58f86df..c1ff31f 100644
--- a/drm/crypto/1.0/ICryptoFactory.hal
+++ b/drm/crypto/1.0/ICryptoFactory.hal
@@ -25,7 +25,7 @@
  * which are used by a codec to decrypt protected video content.
  */
 interface ICryptoFactory {
-    /*
+    /**
      * Determine if a crypto scheme is supported by this HAL
      *
      * @param uuid identifies the crypto scheme in question
@@ -33,20 +33,21 @@
      */
     isCryptoSchemeSupported(uint8_t[16] uuid) generates(bool isSupported);
 
-    /*
+    /**
      * Create a crypto plugin for the specified uuid and scheme-specific
      * initialization data.
      *
      * @param uuid uniquely identifies the drm scheme. See
      * http://dashif.org/identifiers/protection for uuid assignments
      * @param initData scheme-specific init data.
-     * @return the status of the call
-     * @return the created ICryptoPlugin
-    */
+     * @return status the status of the call. If the plugin can't
+     * be created, the HAL implementation must return ERROR_DRM_CANNOT_HANDLE.
+     * @return cryptoPlugin the created ICryptoPlugin
+     */
     createPlugin(uint8_t[16] uuid, vec<uint8_t> initData)
         generates (Status status, ICryptoPlugin cryptoPlugin);
 
-    /*
+    /**
      * Destroy a previously created crypto plugin
      *
      * @return status the status of the call
diff --git a/drm/crypto/1.0/ICryptoPlugin.hal b/drm/crypto/1.0/ICryptoPlugin.hal
index 1255fdb..ee4c1dc 100644
--- a/drm/crypto/1.0/ICryptoPlugin.hal
+++ b/drm/crypto/1.0/ICryptoPlugin.hal
@@ -25,7 +25,7 @@
  * load crypto keys for a codec to decrypt protected video content.
  */
 interface ICryptoPlugin {
-    /*
+    /**
      * Check if the specified mime-type requires a secure decoder
      * component.
      *
@@ -36,7 +36,7 @@
     requiresSecureDecoderComponent(string mime)
         generates(bool secureRequired);
 
-    /*
+    /**
      * Notify a plugin of the currently configured resolution
      *
      * @param width - the display resolutions's width
@@ -44,16 +44,19 @@
      */
     notifyResolution(uint32_t width, uint32_t height);
 
-    /*
+    /**
      * Associate a mediadrm session with this crypto session
      *
      * @param sessionId the MediaDrm session ID to associate with this crypto
      * session
-     * @return the status of the call
+     * @return the status of the call, status must be
+     * ERROR_DRM_SESSION_NOT_OPENED if the session is not opened, or
+     * ERROR_DRM_CANNOT_HANDLE if the operation is not supported by the drm
+     * scheme.
      */
     setMediaDrmSession(vec<uint8_t> sessionId) generates(Status status);
 
-    /*
+    /**
      * Decrypt an array of subsamples from the source memory buffer to the
      * destination memory buffer.
      *
@@ -71,7 +74,14 @@
      * call to operate on a range of subsamples in a single call
      * @param source the input buffer for the decryption
      * @param destination the output buffer for the decryption
-     * @return status the status of the call
+     * @return status the status of the call. The status must be one of
+     * the following: ERROR_DRM_NO_LICENSE if no license keys have been
+     * loaded, ERROR_DRM_LICENSE_EXPIRED if the license keys have expired,
+     * ERROR_DRM_RESOURCE_BUSY if the resources required to perform the
+     * decryption are not available, ERROR_DRM_INSUFFICIENT_OUTPUT_PROTECTION
+     * if required output protections are not active,
+     * ERROR_DRM_SESSION_NOT_OPENED if the decrypt session is not opened, or
+     * ERROR_DRM_CANNOT_HANDLE in other failure cases.
      * @return bytesWritten the number of bytes output from the decryption
      * @return detailedError if the error is a vendor-specific error, the
      * vendor's crypto HAL may provide a detailed error string to help