ACR: yaca_seal.h doxygen fixes

Change-Id: Ia0956240a40fb5a4ac39a1cdee1aeaa93699c578

diff --git a/api/yaca/yaca_seal.h b/api/yaca/yaca_seal.h
index 190be94..40a6f24 100644 (file)
--- a/api/yaca/yaca_seal.h
+++ b/api/yaca/yaca_seal.h
@@ -17,7 +17,7 @@
  */
 
 /**
- * @file seal.h
+ * @file yaca_seal.h
  * @brief
  */
 
@@ -48,15 +48,21 @@ extern "C" {
  *
  * @since_tizen 3.0
  *
- * @param[out] ctx           Newly created context (must be freed with yaca_ctx_free()).
- * @param[in]  pub_key       Public key of the peer that will receive the encrypted data.
- * @param[in]  algo          Symmetric algorithm that will be used.
- * @param[in]  bcm           Block chaining mode for the symmetric algorithm.
- * @param[in]  sym_key_bits  Symmetric key length (in bits) that will be generated.
- * @param[out] sym_key       Generated symmetric key that will be used. It is encrypted with peer's public key.
- * @param[out] iv            Generated initialization vector that will be used.
- *
- * @return YACA_ERROR_NONE on success, negative on error.
+ * @param[out] ctx           Newly created context (must be freed with yaca_ctx_free())
+ * @param[in]  pub_key       Public key of the peer that will receive the encrypted data
+ * @param[in]  algo          Symmetric algorithm that will be used
+ * @param[in]  bcm           Block chaining mode for the symmetric algorithm
+ * @param[in]  sym_key_bits  Symmetric key length (in bits) that will be generated
+ * @param[out] sym_key       Generated symmetric key that will be used,
+ *                           it is encrypted with peer's public key
+ * @param[out] iv            Generated initialization vector that will be used
+ *
+ * @return #YACA_ERROR_NONE on success, negative on error
+ * @retval #YACA_ERROR_NONE Succesful
+ * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL,
+ *                                      incorrect algo, bcm, sym_key_bits, invalid prv_key)
+ * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
+ * @retval #YACA_ERROR_INTERNAL Internal error
  *
  * @see #yaca_enc_algo_e
  * @see #yaca_block_cipher_mode_e
@@ -76,14 +82,19 @@ int yaca_seal_init(yaca_ctx_h *ctx,
  *
  * @since_tizen 3.0
  *
- * @param[in,out] ctx         Context created by yaca_seal_init().
- * @param[in]     plain       Plain text to be encrypted.
- * @param[in]     plain_len   Length of the plain text.
- * @param[out]    cipher      Buffer for the encrypted data (must be allocated by client, see
- *                            yaca_get_output_length()).
- * @param[out]    cipher_len  Length of the encrypted data, actual number of bytes written will be returned here.
+ * @param[in,out] ctx         Context created by yaca_seal_init()
+ * @param[in]     plain       Plain text to be encrypted
+ * @param[in]     plain_len   Length of the plain text
+ * @param[out]    cipher      Buffer for the encrypted data
+ *                            (must be allocated by client, see yaca_get_output_length())
+ * @param[out]    cipher_len  Length of the encrypted data,
+ *                            actual number of bytes written will be returned here
  *
- * @return YACA_ERROR_NONE on success, negative on error.
+ * @return #YACA_ERROR_NONE on success, negative on error
+ * @retval #YACA_ERROR_NONE Succesful
+ * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL, 0,
+ *                                      incorrect context)
+ * @retval #YACA_ERROR_INTERNAL Internal error
  *
  * @see yaca_seal_init()
  * @see yaca_seal_final()
@@ -99,12 +110,17 @@ int yaca_seal_update(yaca_ctx_h ctx,
  *
  * @since_tizen 3.0
  *
- * @param[in,out] ctx         A valid seal context.
- * @param[out]    cipher      Final piece of the encrypted data (must be allocated by client, see
- *                            yaca_get_block_length()).
- * @param[out]    cipher_len  Length of the final piece, actual number of bytes written will be returned here.
+ * @param[in,out] ctx         A valid seal context
+ * @param[out]    cipher      Final piece of the encrypted data
+ *                            (must be allocated by client, see yaca_get_block_length())
+ * @param[out]    cipher_len  Length of the final piece,
+ *                            actual number of bytes written will be returned here
  *
- * @return YACA_ERROR_NONE on success, negative on error.
+ * @return #YACA_ERROR_NONE on success, negative on error
+ * @retval #YACA_ERROR_NONE Succesful
+ * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL,
+ *                                      incorrect context)
+ * @retval #YACA_ERROR_INTERNAL Internal error
  *
  * @see yaca_seal_init()
  * @see yaca_seal_update()
@@ -118,15 +134,22 @@ int yaca_seal_final(yaca_ctx_h ctx,
  *
  * @since_tizen 3.0
  *
- * @param[out] ctx           Newly created context. Must be freed by yaca_ctx_free().
- * @param[in]  prv_key       Private key, part of the pair that was used for the encryption.
- * @param[in]  algo          Symmetric algorithm that was used for the encryption.
- * @param[in]  bcm           Block chaining mode for the symmetric algorithm.
- * @param[in]  sym_key_bits  Symmetric key length (in bits) that was used for the encryption.
- * @param[in]  sym_key       Symmetric key, encrypted with the public key, that was used to encrypt the data.
- * @param[in]  iv            Initialization vector that was used for the encryption.
- *
- * @return YACA_ERROR_NONE on success, negative on error.
+ * @param[out] ctx           Newly created context (must be freed by yaca_ctx_free())
+ * @param[in]  prv_key       Private key, part of the pair that was used for the encryption
+ * @param[in]  algo          Symmetric algorithm that was used for the encryption
+ * @param[in]  bcm           Block chaining mode for the symmetric algorithm
+ * @param[in]  sym_key_bits  Symmetric key length (in bits) that was used for the encryption
+ * @param[in]  sym_key       Symmetric key, encrypted with the public key,
+ *                           that was used to encrypt the data
+ * @param[in]  iv            Initialization vector that was used for the encryption
+ *
+ * @return #YACA_ERROR_NONE on success, negative on error
+ * @retval #YACA_ERROR_NONE Succesful
+ * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL,
+ *                                      incorrect algo, bcm, sym_key_bits,
+ *                                      invalid prv_key, sym_key or iv)
+ * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
+ * @retval #YACA_ERROR_INTERNAL Internal error
  *
  * @see #yaca_enc_algo_e
  * @see #yaca_block_cipher_mode_e
@@ -146,14 +169,19 @@ int yaca_open_init(yaca_ctx_h *ctx,
  *
  * @since_tizen 3.0
  *
- * @param[in,out] ctx         Context created by yaca_open_init().
- * @param[in]     cipher      Cipher text to be decrypted.
- * @param[in]     cipher_len  Length of the cipher text.
- * @param[out]    plain       Buffer for the decrypted data (must be allocated by client, see
- *                            yaca_get_output_length()).
- * @param[out]    plain_len   Length of the decrypted data, actual number of bytes written will be returned here.
+ * @param[in,out] ctx         Context created by yaca_open_init()
+ * @param[in]     cipher      Cipher text to be decrypted
+ * @param[in]     cipher_len  Length of the cipher text
+ * @param[out]    plain       Buffer for the decrypted data
+ *                            (must be allocated by client, see yaca_get_output_length())
+ * @param[out]    plain_len   Length of the decrypted data,
+ *                            actual number of bytes written will be returned here
  *
- * @return YACA_ERROR_NONE on success, negative on error.
+ * @return #YACA_ERROR_NONE on success, negative on error
+ * @retval #YACA_ERROR_NONE Succesful
+ * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL, 0,
+ *                                      incorrect context)
+ * @retval #YACA_ERROR_INTERNAL Internal error
  *
  * @see yaca_open_init()
  * @see yaca_open_final()
@@ -169,12 +197,17 @@ int yaca_open_update(yaca_ctx_h ctx,
  *
  * @since_tizen 3.0
  *
- * @param[in,out] ctx        A valid open context.
- * @param[out]    plain      Final piece of the decrypted data (must be allocated by client, see
- *                           yaca_get_block_length()).
- * @param[out]    plain_len  Length of the final piece, actual number of bytes written will be returned here.
- *
- * @return YACA_ERROR_NONE on success, negative on error.
+ * @param[in,out] ctx        A valid open context
+ * @param[out]    plain      Final piece of the decrypted data
+ *                           (must be allocated by client, see yaca_get_block_length())
+ * @param[out]    plain_len  Length of the final piece,
+ *                           actual number of bytes written will be returned here
+ *
+ * @return #YACA_ERROR_NONE on success, negative on error
+ * @retval #YACA_ERROR_NONE Succesful
+ * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL,
+ *                                      incorrect context)
+ * @retval #YACA_ERROR_INTERNAL Internal error
  *
  * @see yaca_open_init()
  * @see yaca_open_update()