Subject: Re: [PATCH] crypto: clear htmldocs build warnings for crypto/hash
To: "Tobin C. Harding" <me@tobin.cc>
Cc: Herbert Xu <herbert@gondor.apana.org.au>,
        "David S. Miller" <davem@davemloft.net>,
        Bartlomiej Zolnierkiewicz <b.zolnierkie@samsung.com>,
        linux-kernel@vger.kernel.org
From: Kamil Konieczny <k.konieczny@partner.samsung.com>
Message-id: <724b85c9-f3df-15b2-7aa2-4089f232c155@partner.samsung.com>
Date: Mon, 08 Jan 2018 14:11:21 +0100
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101
        Thunderbird/52.5.0
MIME-version: 1.0
In-reply-to: <1515279703-14070-1-git-send-email-me@tobin.cc>
Content-type: text/plain; charset="utf-8"
Content-language: en-US
Content-transfer-encoding: 7bit
CMS-TYPE: 201P
References: <CGME20180106230157epcas2p2a3dc70ac85fbd7861ddf916fde5dd2be@epcas2p2.samsung.com>
        <1515279703-14070-1-git-send-email-me@tobin.cc>
Sender: linux-kernel-owner@vger.kernel.org


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@tobin.cc>
> ---
> 
> 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