Re: [PATCH 3/7] crypto: doc - fix source comments for Sphinx

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Am 16.10.2016 um 05:18 schrieb Stephan Mueller <smueller@xxxxxxxxxx>:

> Update comments to avoid any complaints from Sphinx during compilation.
> 
> Signed-off-by: Stephan Mueller <smueller@xxxxxxxxxx>
> ---
> include/crypto/aead.h     | 14 +++++++-------
> include/crypto/hash.h     |  2 +-
> include/crypto/skcipher.h |  4 ++--
> include/linux/crypto.h    |  4 ++--
> 4 files changed, 12 insertions(+), 12 deletions(-)
> 
> diff --git a/include/crypto/aead.h b/include/crypto/aead.h
> index 12f8432..1bd3a2f 100644
> --- a/include/crypto/aead.h
> +++ b/include/crypto/aead.h
> @@ -55,14 +55,14 @@
> * The scatter list pointing to the input data must contain:
> *
> * * for RFC4106 ciphers, the concatenation of
> - * associated authentication data || IV || plaintext or ciphertext. Note, the
> - * same IV (buffer) is also set with the aead_request_set_crypt call. Note,
> - * the API call of aead_request_set_ad must provide the length of the AAD and
> - * the IV. The API call of aead_request_set_crypt only points to the size of
> - * the input plaintext or ciphertext.
> + *   associated authentication data || IV || plaintext or ciphertext. Note, the
> + *   same IV (buffer) is also set with the aead_request_set_crypt call. Note,
> + *   the API call of aead_request_set_ad must provide the length of the AAD and
> + *   the IV. The API call of aead_request_set_crypt only points to the size of
> + *   the input plaintext or ciphertext.
> *
> * * for "normal" AEAD ciphers, the concatenation of
> - * associated authentication data || plaintext or ciphertext.
> + *   associated authentication data || plaintext or ciphertext.
> *
> * It is important to note that if multiple scatter gather list entries form
> * the input data mentioned above, the first entry must not point to a NULL
> @@ -454,7 +454,7 @@ static inline void aead_request_free(struct aead_request *req)
> * The callback function is registered with the aead_request handle and
> * must comply with the following template
> *
> - *	void callback_function(struct crypto_async_request *req, int error)
> + *	void callback_function(struct crypto_async_request \*req, int error)

Hi Stephan,

compared to DocBook, with sphinx you can use (have to use) the reST markup
in source code comments.

Here, the code example is just a (indented) float text and this is 
why you have to quote the asterisk "\*req,". 

If you want a literal (pre-formatted) block, I recommend to use two colon
and an indented block:

* The callback function is registered with the aead_request handle and
* must comply with the following template::
*
*   void callback_function(struct crypto_async_request *req, int error)
*

If you want a *highlighted* code block, use the code-block directive, e.g:

* The callback function is registered with the aead_request handle and
* must comply with the following template:
*
* .. code-block: c
*
*    void callback_function(struct crypto_async_request *req, int error)
*

-- Markus --


> */
> static inline void aead_request_set_callback(struct aead_request *req,
> 					     u32 flags,
> diff --git a/include/crypto/hash.h b/include/crypto/hash.h
> index 2660588..23f15d0 100644
> --- a/include/crypto/hash.h
> +++ b/include/crypto/hash.h
> @@ -607,7 +607,7 @@ static inline struct ahash_request *ahash_request_cast(
> * The callback function is registered with the &ahash_request handle and
> * must comply with the following template
> *
> - *	void callback_function(struct crypto_async_request *req, int error)
> + *	void callback_function(struct crypto_async_request \*req, int error)
> */
> static inline void ahash_request_set_callback(struct ahash_request *req,
> 					      u32 flags,
> diff --git a/include/crypto/skcipher.h b/include/crypto/skcipher.h
> index cc4d98a..78a1de0 100644
> --- a/include/crypto/skcipher.h
> +++ b/include/crypto/skcipher.h
> @@ -516,7 +516,7 @@ static inline void skcipher_request_zero(struct skcipher_request *req)
> * skcipher_request_set_callback() - set asynchronous callback function
> * @req: request handle
> * @flags: specify zero or an ORing of the flags
> - *         CRYPTO_TFM_REQ_MAY_BACKLOG the request queue may back log and
> + *	   CRYPTO_TFM_REQ_MAY_BACKLOG the request queue may back log and
> *	   increase the wait queue beyond the initial maximum size;
> *	   CRYPTO_TFM_REQ_MAY_SLEEP the request processing may sleep
> * @compl: callback function pointer to be registered with the request handle
> @@ -535,7 +535,7 @@ static inline void skcipher_request_zero(struct skcipher_request *req)
> * The callback function is registered with the skcipher_request handle and
> * must comply with the following template
> *
> - *	void callback_function(struct crypto_async_request *req, int error)
> + *	void callback_function(struct crypto_async_request \*req, int error)
> */
> static inline void skcipher_request_set_callback(struct skcipher_request *req,
> 						 u32 flags,
> diff --git a/include/linux/crypto.h b/include/linux/crypto.h
> index 7cee555..615a326 100644
> --- a/include/linux/crypto.h
> +++ b/include/linux/crypto.h
> @@ -960,7 +960,7 @@ static inline void ablkcipher_request_free(struct ablkcipher_request *req)
> * ablkcipher_request_set_callback() - set asynchronous callback function
> * @req: request handle
> * @flags: specify zero or an ORing of the flags
> - *         CRYPTO_TFM_REQ_MAY_BACKLOG the request queue may back log and
> + *	   CRYPTO_TFM_REQ_MAY_BACKLOG the request queue may back log and
> *	   increase the wait queue beyond the initial maximum size;
> *	   CRYPTO_TFM_REQ_MAY_SLEEP the request processing may sleep
> * @compl: callback function pointer to be registered with the request handle
> @@ -979,7 +979,7 @@ static inline void ablkcipher_request_free(struct ablkcipher_request *req)
> * The callback function is registered with the ablkcipher_request handle and
> * must comply with the following template
> *
> - *	void callback_function(struct crypto_async_request *req, int error)
> + *	void callback_function(struct crypto_async_request \*req, int error)
> */
> static inline void ablkcipher_request_set_callback(
> 	struct ablkcipher_request *req,
> -- 
> 2.7.4
> 
> 
> --
> To unsubscribe from this list: send the line "unsubscribe linux-doc" in
> the body of a message to majordomo@xxxxxxxxxxxxxxx
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

--
To unsubscribe from this list: send the line "unsubscribe linux-crypto" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html



[Index of Archives]     [Kernel]     [Gnu Classpath]     [Gnu Crypto]     [DM Crypt]     [Netfilter]     [Bugtraq]

  Powered by Linux