Re: [PATCH] crypto: clear htmldocs build warnings for crypto/hash

[Kamil Konieczny]

On 07.01.2018 00:01, Tobin C. Harding wrote:
> SPHINX build emits multiple warnings of kind:
> 
> 	warning: duplicate section name 'Note'
> 
> (when building kernel via make target 'htmldocs')
> 
> This is caused by repeated use of comments of form:
> 
> 	* Note: soau soaeusoa uoe
> 
> We can change the format without loss of clarity and clear the build
> warnings.
> 
> Add '**[mandatory]**' or '**[optional]**' as kernel-doc field element
> description prefix
> 
> This renders in HTML as (prefixes in bold)
> 
> final
>     [mandatory] Retrieve result from the driver. This function finalizes the
>     transformation and retrieves the resulting hash from the driver and
>     pushes it back to upper layers. No data processing happens at this
>     point unless hardware requires it to finish the transformation (then
>     the data buffered by the device driver is processed).
> 
> Signed-off-by: Tobin C. Harding <me@xxxxxxxx>
> ---
> 
> This patch begs the question why the other members of struct ahash_alg
> are not marked? Some are marked 'optional' some 'mandatory'. It would
> seem that if the marking were necessary for some members it is necessary
> for all to eliminate ambiguity?
> 
> thanks

import, export are optional
digest is mandatory

see declaration for function
static int crypto_ahash_init_tfm(struct crypto_tfm *tfm)

in crypto/hash.c

setkey is not allowed in hash, but mandatory for HMAC
(as you can find out from description)

>  include/crypto/hash.h | 12 ++++--------
>  1 file changed, 4 insertions(+), 8 deletions(-)
> 
> diff --git a/include/crypto/hash.h b/include/crypto/hash.h
> index 0ed31fd80242..d1cd75faff40 100644
> --- a/include/crypto/hash.h
> +++ b/include/crypto/hash.h
> @@ -71,12 +71,11 @@ struct ahash_request {
>  
>  /**
>   * struct ahash_alg - asynchronous message digest definition
> - * @init: Initialize the transformation context. Intended only to initialize the
> + * @init: **[mandatory]** Initialize the transformation context. Intended only to initialize the
>   *	  state of the HASH transformation at the beginning. This shall fill in
>   *	  the internal structures used during the entire duration of the whole
>   *	  transformation. No data processing happens at this point.
> - *	  Note: mandatory.
> - * @update: Push a chunk of data into the driver for transformation. This
> + * @update: **[mandatory]** Push a chunk of data into the driver for transformation. This
>   *	   function actually pushes blocks of data from upper layers into the
>   *	   driver, which then passes those to the hardware as seen fit. This
>   *	   function must not finalize the HASH transformation by calculating the
> @@ -85,20 +84,17 @@ struct ahash_request {
>   *	   context, as this function may be called in parallel with the same
>   *	   transformation object. Data processing can happen synchronously
>   *	   [SHASH] or asynchronously [AHASH] at this point.
> - *	   Note: mandatory.
> - * @final: Retrieve result from the driver. This function finalizes the
> + * @final: **[mandatory]** Retrieve result from the driver. This function finalizes the
>   *	   transformation and retrieves the resulting hash from the driver and
>   *	   pushes it back to upper layers. No data processing happens at this
>   *	   point unless hardware requires it to finish the transformation
>   *	   (then the data buffered by the device driver is processed).
> - *	   Note: mandatory.
> - * @finup: Combination of @update and @final. This function is effectively a
> + * @finup: **[optional]** Combination of @update and @final. This function is effectively a
>   *	   combination of @update and @final calls issued in sequence. As some
>   *	   hardware cannot do @update and @final separately, this callback was
>   *	   added to allow such hardware to be used at least by IPsec. Data
>   *	   processing can happen synchronously [SHASH] or asynchronously [AHASH]
>   *	   at this point.
> - *	   Note: optional.
>   * @digest: Combination of @init and @update and @final. This function
>   *	    effectively behaves as the entire chain of operations, @init,
>   *	    @update and @final issued in sequence. Just like @finup, this was
> 

-- 
Best regards,
Kamil Konieczny
Samsung R&D Institute Poland