-/*
- * Hash Functions
- * --------------
- *
- * For hash function 'xxx', the following elements are defined:
- *
- * br_xxx_vtable
- * An externally defined instance of br_hash_class.
- *
- * br_xxx_SIZE
- * A macro that evaluates to the output size (in bytes) of the
- * hash function.
- *
- * br_xxx_ID
- * A macro that evaluates to a symbolic identifier for the hash
- * function. Such identifiers are used with HMAC and signature
- * algorithm implementations.
- * NOTE: the numerical value of these identifiers MUST match the
- * constants for hash function identification in TLS 1.2 (see RFC
- * 5246, section 7.4.1.4.1). These are values 1 to 6, for MD5,
- * SHA-1, SHA-224, SHA-256, SHA-384 and SHA-512, respectively.
- *
- * br_xxx_context
- * Context for an ongoing computation. It is allocated by the
- * caller, and a pointer to it is passed to all functions. A
- * context contains no interior pointer, so it can be moved around
- * and cloned (with a simple memcpy() or equivalent) in order to
- * capture the function state at some point. Computations that use
- * distinct context structures are independent of each other. The
- * first field of br_xxx_context is always a pointer to the
- * br_xxx_vtable structure; br_xxx_init() sets that pointer.
- *
- * br_xxx_init(br_xxx_context *ctx)
- * Initialize the provided context. Previous contents of the structure
- * are ignored. This calls resets the context to the start of a new
- * hash computation.
- *
- * br_xxx_update(br_xxx_context *ctx, const void *data, size_t len)
- * Add some more bytes to the hash computation represented by the
- * provided context.
- *
- * br_xxx_out(const br_xxx_context *ctx, void *out)
- * Complete the hash computation and write the result in the provided
- * buffer. The output buffer MUST be large enough to accomodate the
- * result. The context is NOT modified by this operation, so this
- * function can be used to get a "partial hash" while still keeping
- * the possibility of adding more bytes to the input.
- *
- * br_xxx_state(const br_xxx_context *ctx, void *out)
- * Get a copy of the "current state" for the computation so far. For
- * MD functions (MD5, SHA-1, SHA-2 family), this is the running state
- * resulting from the processing of the last complete input block.
- * Returned value is the current input length (in bytes).
- *
- * br_xxx_set_state(br_xxx_context *ctx, const void *stb, uint64_t count)
- * Set the internal state to the provided values. The 'stb' and 'count'
- * values shall match that which was obtained from br_xxx_state(). This
- * restores the hash state only if the state values were at an
- * appropriate block boundary. This does NOT set the 'vtable' pointer
- * in the context.
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** \file bearssl_hash.h
+ *
+ * # Hash Functions
+ *
+ * This file documents the API for hash functions.
+ *
+ *
+ * ## Procedural API
+ *
+ * For each implemented hash function, of name "`xxx`", the following
+ * elements are defined:
+ *
+ * - `br_xxx_vtable`
+ *
+ * An externally defined instance of `br_hash_class`.
+ *
+ * - `br_xxx_SIZE`
+ *
+ * A macro that evaluates to the output size (in bytes) of the
+ * hash function.
+ *
+ * - `br_xxx_ID`
+ *
+ * A macro that evaluates to a symbolic identifier for the hash
+ * function. Such identifiers are used with HMAC and signature
+ * algorithm implementations.
+ *
+ * NOTE: for the "standard" hash functions defined in [the TLS
+ * standard](https://tools.ietf.org/html/rfc5246#section-7.4.1.4.1),
+ * the symbolic identifiers match the constants used in TLS, i.e.
+ * 1 to 6 for MD5, SHA-1, SHA-224, SHA-256, SHA-384 and SHA-512,
+ * respectively.
+ *
+ * - `br_xxx_context`
+ *
+ * Context for an ongoing computation. It is allocated by the
+ * caller, and a pointer to it is passed to all functions. A
+ * context contains no interior pointer, so it can be moved around
+ * and cloned (with a simple `memcpy()` or equivalent) in order to
+ * capture the function state at some point. Computations that use
+ * distinct context structures are independent of each other. The
+ * first field of `br_xxx_context` is always a pointer to the
+ * `br_xxx_vtable` structure; `br_xxx_init()` sets that pointer.
+ *
+ * - `br_xxx_init(br_xxx_context *ctx)`
+ *
+ * Initialise the provided context. Previous contents of the structure
+ * are ignored. This calls resets the context to the start of a new
+ * hash computation; it also sets the first field of the context
+ * structure (called `vtable`) to a pointer to the statically
+ * allocated constant `br_xxx_vtable` structure.
+ *
+ * - `br_xxx_update(br_xxx_context *ctx, const void *data, size_t len)`
+ *
+ * Add some more bytes to the hash computation represented by the
+ * provided context.
+ *
+ * - `br_xxx_out(const br_xxx_context *ctx, void *out)`
+ *
+ * Complete the hash computation and write the result in the provided
+ * buffer. The output buffer MUST be large enough to accomodate the
+ * result. The context is NOT modified by this operation, so this
+ * function can be used to get a "partial hash" while still keeping
+ * the possibility of adding more bytes to the input.
+ *
+ * - `br_xxx_state(const br_xxx_context *ctx, void *out)`
+ *
+ * Get a copy of the "current state" for the computation so far. For
+ * MD functions (MD5, SHA-1, SHA-2 family), this is the running state
+ * resulting from the processing of the last complete input block.
+ * Returned value is the current input length (in bytes).
+ *
+ * - `br_xxx_set_state(br_xxx_context *ctx, const void *stb, uint64_t count)`
+ *
+ * Set the internal state to the provided values. The 'stb' and
+ * 'count' values shall match that which was obtained from
+ * `br_xxx_state()`. This restores the hash state only if the state
+ * values were at an appropriate block boundary. This does NOT set
+ * the `vtable` pointer in the context.