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
diff --git a/drm/drm/1.0/IDrmFactory.hal b/drm/drm/1.0/IDrmFactory.hal
index a4ee0f1..80cb941 100644
--- a/drm/drm/1.0/IDrmFactory.hal
+++ b/drm/drm/1.0/IDrmFactory.hal
@@ -27,7 +27,7 @@
  */
 
 interface IDrmFactory {
-    /*
+    /**
      * Determine if a crypto scheme is supported by this HAL
      *
      * @param uuid identifies the crypto scheme in question
@@ -35,20 +35,21 @@
      */
     isCryptoSchemeSupported(uint8_t[16] uuid) generates(bool isSupported);
 
-    /*
+    /**
      * Create a drm plugin instance 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 status the status of the call. If the plugin can't
+     * be created, the HAL implementation must return ERROR_DRM_CANNOT_HANDLE.
      * @return the created IDrmPlugin
      */
     createPlugin(uint8_t[16] uuid, vec<uint8_t> initData)
         generates (Status status, IDrmPlugin drmPlugin);
 
-    /*
+    /**
      * Destroy a previously created drm plugin
      * @return status the status of the call
      */
diff --git a/drm/drm/1.0/IDrmPlugin.hal b/drm/drm/1.0/IDrmPlugin.hal
index 7f396d9..cc15cfd 100644
--- a/drm/drm/1.0/IDrmPlugin.hal
+++ b/drm/drm/1.0/IDrmPlugin.hal
@@ -30,7 +30,13 @@
     /**
      * Open a new session with the DrmPlugin object. A session ID is returned
      * in the sessionId parameter.
-     * @return status the status of the call
+     * @return status the status of the call. The status must be one of
+     * ERROR_DRM_NOT_PROVISIONED if the device requires provisioning before
+     * it can open a session, ERROR_DRM_RESOURCE_BUSY if there are insufficent
+     * resources available to open a session, ERROR_DRM_CANNOT_HANDLE,
+     * if openSession is not supported at the time of the call or
+     * ERROR_DRM_INVALID_STATE if the HAL is in a state where a session cannot
+     * be opened.
      */
     openSession() generates (SessionId sessionId, Status status);
 
@@ -38,7 +44,10 @@
      * Close a session on the DrmPlugin object
      *
      * @param sessionId the session id the call applies to
-     * @return status the status of the call
+     * @return status the status of the call.  The status must be one of
+     * ERROR_DRM_SESSION_NOT_OPENED if the session is not opened,
+     * BAD_VALUE if the sessionId is invalid or ERROR_DRM_INVALID_STATE
+     * if the HAL is in a state where the session cannot be closed.
      */
     closeSession(SessionId sessionId) generates (Status status);
 
@@ -72,7 +81,13 @@
      * subsequent key request used to refresh the keys in a license. RELEASE
      * corresponds to a keyType of RELEASE, which indicates keys are being
      * released.
-     * @return status the status of the call
+     * @return status the status of the call.  The status must be one of
+     * ERROR_DRM_SESSION_NOT_OPENED if the session is not opened,
+     * ERROR_DRM_NOT_PROVISIONED if the device requires provisioning before
+     * it can generate a key request, ERROR_DRM_CANNOT_HANDLE if keyKeyRequest
+     * is not supported at the time of the call, BAD_VALUE if any parameters
+     * are invalid or ERROR_DRM_INVALID_STATE if the HAL is in a state where
+     * a key request cannot be generated.
      * @return defaultUrl the URL that the request may be sent to, if
      * provided by the drm HAL. The app may choose to override this
      * URL.
@@ -98,8 +113,14 @@
      * to later restore the keys to a new session with the method restoreKeys.
      * When the response is for a streaming or release request, no keySetId is
      * returned.
-     *
-     * @return status the status of the call
+     * @return status the status of the call.  The status must be one of
+     * ERROR_DRM_SESSION_NOT_OPENED if the session is not opened,
+     * ERROR_DRM_NOT_PROVISIONED if the device requires provisioning before
+     * it can handle the key response, ERROR_DRM_DEVICE_REVOKED if the device
+     * has been disabled by the license policy, ERROR_DRM_CANNOT_HANDLE if
+     * provideKeyResponse is not supported at the time of the call, BAD_VALUE
+     * if any parameters are invalid or ERROR_DRM_INVALID_STATE if the HAL is
+     * in a state where a key response cannot be handled.
      */
     provideKeyResponse(vec<uint8_t> scope,
         vec<uint8_t> response) generates (vec<uint8_t> keySetId, Status status);
@@ -108,7 +129,10 @@
      * Remove the current keys from a session
      *
      * @param sessionId the session id the call applies to
-     * @return status the status of the call
+     * @return status the status of the call.  The status must be one of
+     * ERROR_DRM_SESSION_NOT_OPENED if the session is not opened,
+     * BAD_VALUE if the sessionId is invalid or ERROR_DRM_INVALID_STATE
+     * if the HAL is in a state where the keys cannot be removed.
      */
     removeKeys(SessionId sessionId) generates (Status status);
 
@@ -118,12 +142,15 @@
      * @param sessionId the session id the call applies to
      * @param keySetId identifies the keys to load, obtained from a prior
      * call to provideKeyResponse().
-     * @return status the status of the call
+     * @return status the status of the call. The status must be one of
+     * ERROR_DRM_SESSION_NOT_OPENED if the session is not opened,
+     * BAD_VALUE if any parameters are invalid or ERROR_DRM_INVALID_STATE
+     * if the HAL is in a state where keys cannot be restored.
      */
     restoreKeys(SessionId sessionId,
         vec<uint8_t> keySetId) generates (Status status);
 
-    /*
+    /**
      * Request an informative description of the license for the session. The
      * status is in the form of {name, value} pairs. Since DRM license policies
      * vary by vendor, the specific status field names are determined by each
@@ -132,7 +159,10 @@
      *
      * @param sessionId the session id the call applies to
      * @return infoList a list of name value pairs describing the license
-     * @return status the status of the call
+     * @return status the status of the call. The status must be one of
+     * ERROR_DRM_SESSION_NOT_OPENED if the session is not opened,
+     * BAD_VALUE if the sessionId is invalid or ERROR_DRM_INVALID_STATE
+     * if the HAL is in a state where key status cannot be queried.
      */
     queryKeyStatus(SessionId sessionId)
         generates (KeyedVector infoList, Status status);
@@ -148,7 +178,10 @@
      * certificate authority (CA) is an entity which issues digital certificates
      * for use by other parties. It is an example of a trusted third party
      * @return if successful the opaque certirequest blob is returned
-     * @return status the status of the call
+     * @return status the status of the call. The status must be one of
+     * BAD_VALUE if the sessionId is invalid or ERROR_DRM_INVALID_STATE
+     * if the HAL is in a state where the provision request cannot be
+     * generated.
      */
     getProvisionRequest(string certificateType, string certificateAuthority)
         generates (vec<uint8_t> request, string defaultUrl, Status status);
@@ -165,7 +198,11 @@
      * @return wrappedKey an opaque object containing encrypted private key
      * material to be used by signRSA when computing an RSA signature on a
      * message, see the signRSA method.
-     * @return status the status of the call
+     * @return status the status of the call. The status must be one of
+     * ERROR_DRM_DEVICE_REVOKED if the device has been disabled by the license
+     * policy, BAD_VALUE if any parameters are invalid or ERROR_DRM_INVALID_STATE
+     * if the HAL is in a state where the provision response cannot be
+     * handled.
      */
     provideProvisionResponse(vec<uint8_t> response)
         generates (vec<uint8_t> certificate, vec<uint8_t> wrappedKey,
@@ -194,40 +231,48 @@
      * Get all secure stops on the device
      *
      * @return secureStops a list of the secure stop opaque objects
-     * @return status the status of the call
+     * @return status the status of the call. The status must be
+     * ERROR_DRM_INVALID_STATE if the HAL is in a state where the secure stops
+     * cannot be returned.
      */
     getSecureStops() generates
         (vec<SecureStop> secureStops, Status status);
 
     /**
-    * Get all secure stops by secure stop ID
-    *
-    * @param secureStopId the ID of the secure stop to return. The
-    * secure stop ID is delivered by the key server as part of the key
-    * response and must also be known by the app.
-    *
-    * @return the secure stop opaque object
-    * @return status the status of the call
-    */
+     * Get all secure stops by secure stop ID
+     *
+     * @param secureStopId the ID of the secure stop to return. The
+     * secure stop ID is delivered by the key server as part of the key
+     * response and must also be known by the app.
+     *
+     * @return secureStop the secure stop opaque object
+     * @return status the status of the call. The status must be one of
+     * BAD_VALUE if the secureStopId is invalid or ERROR_DRM_INVALID_STATE
+     * if the HAL is in a state where the secure stop cannot be returned.
+     */
     getSecureStop(SecureStopId secureStopId)
         generates (SecureStop secureStop, Status status);
 
     /**
      * Release all secure stops on the device
      *
-     * @return status the status of the call
+     * @return status the status of the call. The status must be one of
+     * ERROR_DRM_INVALID_STATE if the HAL is in a state where the secure
+     * stops cannot be released.
      */
     releaseAllSecureStops() generates (Status status);
 
     /**
-    * Release a secure stop by secure stop ID
-    *
-    * @param secureStopId the ID of the secure stop to release. The
-    * secure stop ID is delivered by the key server as part of the key
-    * response and must also be known by the app.
-    *
-    * @return status the status of the call
-    */
+     * Release a secure stop by secure stop ID
+     *
+     * @param secureStopId the ID of the secure stop to release. The
+     * secure stop ID is delivered by the key server as part of the key
+     * response and must also be known by the app.
+     *
+     * @return status the status of the call. The status must be one of
+     * BAD_VALUE if the secureStopId is invalid or ERROR_DRM_INVALID_STATE
+     * if the HAL is in a state where the secure stop cannot be released.
+     */
     releaseSecureStop(vec<uint8_t> secureStopId) generates (Status status);
 
     /**
@@ -252,8 +297,11 @@
      * Read a string property value given the property name.
      *
      * @param propertyName the name of the property
-     * @return the property value string
-     * @return status the status of the call
+     * @return value the property value string
+     * @return status the status of the call. The status must be one of
+     * BAD_VALUE if the property name is invalid, ERROR_DRM_CANNOT_HANDLE
+     * if the property is not supported, or ERROR_DRM_INVALID_STATE if the
+     * HAL is in a state where the property cannot be obtained.
      */
     getPropertyString(string propertyName)
         generates (string value, Status status);
@@ -262,8 +310,11 @@
      * Read a byte array property value given the property name.
      *
      * @param propertyName the name of the property
-     * @return the property value byte array
-     * @return status the status of the call
+     * @return value the property value byte array
+     * @return status the status of the call. The status must be one of
+     * BAD_VALUE if the property name is invalid, ERROR_DRM_CANNOT_HANDLE
+     * if the property is not supported, or ERROR_DRM_INVALID_STATE if the
+     * HAL is in a state where the property cannot be obtained.
      */
     getPropertyByteArray(string propertyName)
         generates (vec<uint8_t> value, Status status);
@@ -273,7 +324,10 @@
      *
      * @param propertyName the name of the property
      * @param value the value to write
-     * @return status the status of the call
+     * @return status the status of the call. The status must be one of
+     * BAD_VALUE if the property name is invalid, ERROR_DRM_CANNOT_HANDLE
+     * if the property is not supported, or ERROR_DRM_INVALID_STATE if the
+     * HAL is in a state where the property cannot be set.
      */
     setPropertyString(string propertyName, string value )
         generates (Status status);
@@ -283,7 +337,10 @@
      *
      * @param propertyName the name of the property
      * @param value the value to write
-     * @return status the status of the call
+     * @return status the status of the call. The status must be one of
+     * BAD_VALUE if the property name is invalid, ERROR_DRM_CANNOT_HANDLE
+     * if the property is not supported, or ERROR_DRM_INVALID_STATE if the
+     * HAL is in a state where the property cannot be set.
      */
     setPropertyByteArray(string propertyName, vec<uint8_t> value )
         generates (Status status);
@@ -301,7 +358,10 @@
      * @param algorithm the algorithm to use. The string conforms to JCA
      * Standard Names for Cipher Transforms and is case insensitive. An
      * example algorithm is "AES/CBC/PKCS5Padding".
-     * @return status the status of the call
+     * @return status the status of the call. The status must be one of
+     * ERROR_DRM_SESSION_NOT_OPENED if the session is not opened,
+     * BAD_VALUE if any parameters are invalid or ERROR_DRM_INVALID_STATE
+     * if the HAL is in a state where the algorithm cannot be set.
      */
     setCipherAlgorithm(SessionId sessionId, string algorithm)
         generates (Status status);
@@ -313,7 +373,10 @@
      * @param algorithm the algorithm to use. The string conforms to JCA
      * Standard Names for Mac Algorithms and is case insensitive. An example MAC
      * algorithm string is "HmacSHA256".
-     * @return status the status of the call
+     * @return status the status of the call. The status must be one of
+     * ERROR_DRM_SESSION_NOT_OPENED if the session is not opened,
+     * BAD_VALUE if any parameters are invalid or ERROR_DRM_INVALID_STATE
+     * if the HAL is in a state where the algorithm cannot be set.
      */
     setMacAlgorithm(SessionId sessionId, string algorithm)
         generates (Status status);
@@ -328,7 +391,11 @@
      * @param input the input data to encrypt
      * @param iv the initialization vector to use for encryption
      * @return output the decrypted data
-     * @return status the status of the call
+     * @return status the status of the call. The status must be one of
+     * ERROR_DRM_SESSION_NOT_OPENED if the session is not opened,
+     * BAD_VALUE if any parameters are invalid or ERROR_DRM_INVALID_STATE
+     * if the HAL is in a state where the encrypt operation cannot be
+     * performed.
      */
     encrypt(SessionId sessionId, vec<uint8_t> keyId, vec<uint8_t> input,
         vec<uint8_t> iv)
@@ -344,7 +411,11 @@
      * @param input the input data to decrypt
      * @param iv the initialization vector to use for decryption
      * @return output the decrypted data
-     * @return status the status of the call
+     * @return status the status of the call. The status must be one of
+     * ERROR_DRM_SESSION_NOT_OPENED if the session is not opened,
+     * BAD_VALUE if any parameters are invalid or ERROR_DRM_INVALID_STATE
+     * if the HAL is in a state where the decrypt operation cannot be
+     * performed.
      */
     decrypt(SessionId sessionId, vec<uint8_t> keyId, vec<uint8_t> input,
         vec<uint8_t> iv) generates (vec<uint8_t> output, Status status);
@@ -357,8 +428,12 @@
      * @param sessionId the session id the call applies to
      * @param keyId the ID of the key to use for decryption
      * @param message the message to compute a signature over
-     * @return the computed signature
-     * @return status the status of the call
+     * @return signature the computed signature
+     * @return status the status of the call. The status must be one of
+     * ERROR_DRM_SESSION_NOT_OPENED if the session is not opened,
+     * BAD_VALUE if any parameters are invalid or ERROR_DRM_INVALID_STATE
+     * if the HAL is in a state where the sign operation cannot be
+     * performed.
      */
     sign(SessionId sessionId, vec<uint8_t> keyId, vec<uint8_t> message)
         generates (vec<uint8_t> signature, Status status);
@@ -371,7 +446,11 @@
      * @param sessionId the session id the call applies to
      * @param keyId the ID of the key to use for decryption
      * @param message the message to compute a hash of
-     * @return status the status of the call
+     * @return status the status of the call. The status must be one of
+     * ERROR_DRM_SESSION_NOT_OPENED if the session is not opened,
+     * BAD_VALUE if any parameters are invalid or ERROR_DRM_INVALID_STATE
+     * if the HAL is in a state where the verify operation cannot be
+     * performed.
      */
     verify(SessionId sessionId, vec<uint8_t> keyId, vec<uint8_t> message,
         vec<uint8_t> signature) generates (bool match, Status status);
@@ -383,10 +462,14 @@
      * @param algorithm the signing algorithm, such as "RSASSA-PSS-SHA1"
      * or "PKCS1-BlockType1"
      * @param sessionId the session id the call applies to
-     * @param wrappedKey the private key returned during provisioning
-     * as returned by provideProvisionResponse.
+     * @param wrappedKey the private key returned during provisioning as
+     * returned by provideProvisionResponse.
      * @return signature the RSA signature computed over the message
-     * @return status the status of the call
+     * @return status the status of the call. The status must be one of
+     * ERROR_DRM_SESSION_NOT_OPENED if the session is not opened,
+     * BAD_VALUE if any parameters are invalid or ERROR_DRM_INVALID_STATE
+     * if the HAL is in a state where the signRSA operation cannot be
+     * performed.
      */
     signRSA(SessionId sessionId, string algorithm, vec<uint8_t> message,
         vec<uint8_t> wrappedkey)