[PATCH 19/20] Improve documentation of libfsverity.h API

[Jes Sorensen <jes.sorensen@xxxxxxxxx>]

From: Jes Sorensen <jsorensen@xxxxxx>

Signed-off-by: Jes Sorensen <jsorensen@xxxxxx>
---
 libfsverity.h | 27 +++++++++++++++++++--------
 1 file changed, 19 insertions(+), 8 deletions(-)

diff --git a/libfsverity.h b/libfsverity.h
index 4f0f885..c4f6b8d 100644
--- a/libfsverity.h
+++ b/libfsverity.h
@@ -58,17 +58,21 @@ struct libfsverity_signature_params {
 
 /*
  * libfsverity_compute_digest - Compute digest of a file
+ *          An fsverity digest is the root of the Merkle tree of the file.
+ *          Not to be confused with a traditional file digests computed over
+ *          the entire file.
  * @fd: open file descriptor of file to compute digest for
  * @params: struct libfsverity_merkle_tree_params specifying hash algorithm,
  *	    block size, version, and optional salt parameters.
  *	    reserved parameters must be zero.
- * @digest_ret: Pointer to pointer for computed digest
+ * @digest_ret: Pointer to pointer for computed digest.
  *
  * Returns:
  * * 0 for success, -EINVAL for invalid input arguments, -ENOMEM if failed
  *   to allocate memory, -EBADF if fd is invalid, and -EAGAIN if root hash
  *   fails to compute.
- * * digest_ret returns a pointer to the digest on success.
+ * * digest_ret returns a pointer to the digest on success. The digest object
+ *   is allocated by libfsverity and must be freed by the caller.
  */
 int
 libfsverity_compute_digest(void *fd, size_t file_size,
@@ -78,6 +82,12 @@ libfsverity_compute_digest(void *fd, size_t file_size,
 
 /*
  * libfsverity_sign_digest - Sign previously computed digest of a file
+ *          This is signature is used by the file system to validate the
+ *          signed file measurement against a public key loaded into the
+ *          .fs-verity kernel keyring, when CONFIG_FS_VERITY_BUILTIN_SIGNATURES
+ *          is enabled. The signature is formatted as PKCS#7 stored in DER
+ *          format. See Documentation/filesystems/fsverity.rst for further
+ *          details.
  * @digest: pointer to previously computed digest
  * @sig_params: struct libfsverity_signature_params providing filenames of
  *          the keyfile and certificate file. Reserved parameters must be zero.
@@ -87,7 +97,8 @@ libfsverity_compute_digest(void *fd, size_t file_size,
  * Returns:
  * * 0 for success, -EINVAL for invalid input arguments, -EAGAIN if key or
  *   certificate files fail to read, or if signing the digest fails.
- * * sig_ret returns a pointer to the signed digest on success.
+ * * sig_ret returns a pointer to the signed digest on success. This object
+ *   is allocated by libfsverity_sign_digest and must be freed by the caller.
  * * sig_size_ret returns the size of the signed digest on success.
  */
 int
@@ -100,7 +111,7 @@ libfsverity_sign_digest(const struct libfsverity_digest *digest,
  * @name: Pointer to name of hash algorithm
  *
  * Returns:
- * uint16_t containing hash algorithm number, zero on error.
+ * uint16_t containing hash algorithm number, zero if not found.
  */
 uint16_t libfsverity_find_hash_alg_by_name(const char *name);
 
@@ -109,7 +120,7 @@ uint16_t libfsverity_find_hash_alg_by_name(const char *name);
  * @alg_nr: Valid hash algorithm number
  *
  * Returns:
- * int containing size of digest, -1 on error.
+ * int containing size of digest, -1 if algorithm is not known.
  */
 int libfsverity_digest_size(uint16_t alg_nr);
 
@@ -118,9 +129,9 @@ int libfsverity_digest_size(uint16_t alg_nr);
  * @name: Number of hash algorithm
  *
  * Returns:
- *  New allocated string containing name of algorithm.
- *  String must be freed by caller.
- * NULL on error
+ * New allocated string containing name of algorithm.
+ *  The string must be freed by caller.
+ * NULL if algorithm is not known.
  */
 char *libfsverity_hash_name(uint16_t num);
 
-- 
2.25.3