Re: [PATCH net-next v8 04/10] lib: packing: document recently added APIs

[Vladimir Oltean <vladimir.oltean@nxp.com>]

On Tue, Dec 03, 2024 at 03:53:50PM -0800, Jacob Keller wrote:
> Extend the documentation for the packing library, covering the intended use
> for the recently added APIs. This includes the pack() and unpack() macros,
> as well as the pack_fields() and unpack_fields() macros.
> 
> Add a note that the packing() API is now deprecated in favor of pack() and
> unpack().
> 
> For the pack_fields() and unpack_fields() APIs, explain the rationale for
> when a driver may want to select this API. Provide an example which shows
> how to define the fields and call the pack_fields() and unpack_fields()
> macros.
> 
> Signed-off-by: Vladimir Oltean <vladimir.oltean@nxp.com>
> Signed-off-by: Jacob Keller <jacob.e.keller@intel.com>
> ---
>  Documentation/core-api/packing.rst | 118 +++++++++++++++++++++++++++++++++++--
>  1 file changed, 113 insertions(+), 5 deletions(-)
> 
> diff --git a/Documentation/core-api/packing.rst b/Documentation/core-api/packing.rst
> index 821691f23c541cee27995bb1d77e23ff04f82433..30fc2328f789920e27a1bcf3945a6793894ef1d4 100644
> --- a/Documentation/core-api/packing.rst
> +++ b/Documentation/core-api/packing.rst
> @@ -227,11 +227,119 @@ Intended use
>  
>  Drivers that opt to use this API first need to identify which of the above 3
>  quirk combinations (for a total of 8) match what the hardware documentation
> -describes. Then they should wrap the packing() function, creating a new
> -xxx_packing() that calls it using the proper QUIRK_* one-hot bits set.
> +describes.
> +
> +There are 3 supported usage patterns, detailed below.
> +
> +packing()
> +^^^^^^^^^
> +
> +This API function is deprecated.
>  
>  The packing() function returns an int-encoded error code, which protects the
>  programmer against incorrect API use.  The errors are not expected to occur
> -during runtime, therefore it is reasonable for xxx_packing() to return void
> -and simply swallow those errors. Optionally it can dump stack or print the
> -error description.
> +during runtime, therefore it is reasonable to wrap packing() into a custom
> +function which returns void and simply swallow those errors. Optionally it can

returns (...) and swallows

> +dump stack or print the error description.