--- a/ChangeLog	Sat May 05 17:42:46 2018 +0200
+++ b/ChangeLog	Sat May 05 17:50:51 2018 +0200
@@ -1,3 +1,8 @@
+2018-05-05  Bruno Haible  <bruno@clisp.org>
+
+	af_alg: Add documentation.
+	* lib/af_alg.h: Add comments.
+
 2018-05-05  Bruno Haible  <bruno@clisp.org>
 
 	sha512: Add tests.

--- a/lib/af_alg.h	Sat May 05 17:42:46 2018 +0200
+++ b/lib/af_alg.h	Sat May 05 17:50:51 2018 +0200
@@ -15,7 +15,16 @@
    You should have received a copy of the GNU General Public License
    along with this program; if not, see <https://www.gnu.org/licenses/>.  */
 
-/* Written by Matteo Croce <mcroce@redhat.com>, 2018. */
+/* Written by Matteo Croce <mcroce@redhat.com>, 2018.
+   Documentation by Bruno Haible <bruno@clisp.org>, 2018.  */
+
+/* This file declares specific functions for computing message digests
+   using the Linux kernel crypto API, if available.  This kernel API gives
+   access to specialized crypto instructions (that would also be available
+   in user space) or to crypto devices (not directly available in user space).
+
+   For a more complete set of facilities that use the Linux kernel crypto API,
+   look at libkcapi.  */
 
 #ifndef AF_ALG_H
 # define AF_ALG_H 1
@@ -29,13 +38,32 @@
 
 # ifdef HAVE_LINUX_IF_ALG_H
 
+/* Computes a message digest of the contents of a file.
+   STREAM is an open file stream.  Regular files are handled more efficiently
+   than other types of files.
+   ALG is the message digest algorithm.  The supported algorithms are listed in
+   the file /proc/crypto.
+   RESBLOCK points to a block of HASHLEN bytes, for the result. HASHLEN must be
+   the length of the message digest, in bytes, in particular:
+
+      alg    | hashlen
+      -------+--------
+      md5    | 16
+      sha1   | 20
+      sha224 | 28
+      sha256 | 32
+      sha384 | 48
+      sha512 | 64
+
+   If successful, this function fills RESBLOCK and returns 0.
+   Upon failure, it returns a negated error code.  */
 int
-afalg_stream (FILE * stream, void *resblock, const char *alg, ssize_t hashlen);
+afalg_stream (FILE *stream, void *resblock, const char *alg, ssize_t hashlen);
 
 # else
 
 static int
-afalg_stream (FILE * stream, void *resblock, const char *alg, ssize_t hashlen)
+afalg_stream (FILE *stream, void *resblock, const char *alg, ssize_t hashlen)
 {
   return -EAFNOSUPPORT;
 }
@@ -46,4 +74,4 @@
 }
 # endif
 
-#endif
+#endif /* AF_ALG_H */