Re: [PATCH 1/4] padata: update documentation

[Jonathan Corbet <corbet@lwn.net>]

On Wed, 20 Nov 2019 13:54:09 -0500
Daniel Jordan <daniel.m.jordan@oracle.com> wrote:

> Remove references to unused functions and update to reflect the new
> struct padata_shell.
> 
> Fixes: 815613da6a67 ("kernel/padata.c: removed unused code")
> Signed-off-by: Daniel Jordan <daniel.m.jordan@oracle.com>
> Cc: Eric Biggers <ebiggers@kernel.org>
> Cc: Herbert Xu <herbert@gondor.apana.org.au>
> Cc: Jonathan Corbet <corbet@lwn.net>
> Cc: Steffen Klassert <steffen.klassert@secunet.com>
> Cc: linux-crypto@vger.kernel.org
> Cc: linux-doc@vger.kernel.org
> Cc: linux-kernel@vger.kernel.org
> ---
>  Documentation/padata.txt | 50 +++++++++++++++++++++-------------------
>  1 file changed, 26 insertions(+), 24 deletions(-)

This all seems fine - it's better than not doing it - but can I put in a
request or two?

 - This document is already formatted as RST, and your changes continue
   that.  Can we please move it to Documentation/core-api/padata.rst and
   add it to the TOC tree there?  Then it can become part of our formatted
   docs.

 - The padata code seems to be nicely equipped with kerneldoc comments; it
   would be awfully nice to pull them into the document directly rather
   than replicating the API there.  (Why does the document do that now?
   Blame the bozo who originally wrote it :)  That would make the document
   more complete and easier to maintain going forward.

For added goodness we could stick in an SPDX tag while we're at it.

Thanks,

jon