Re: [PATCH 6/6] docs: efi: add CPER functions to driver-api

[Jonathan Cameron <Jonathan.Cameron@Huawei.com>]

On Mon,  8 Jul 2024 13:18:15 +0200
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:

> There are two kernel-doc like descriptions at cper, which is used
> by other parts of cper and on ghes driver. They both have kernel-doc
> like descriptions.
> 
> Change the tags for them to be actual kernel-doc tags and add them
> to the driver-api documentaion at the UEFI section.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Other than the blob at the end that belongs in earlier patch LGTM.

Reviewed-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>

> ---
>  Documentation/driver-api/firmware/efi/index.rst | 11 ++++++++---
>  drivers/firmware/efi/cper.c                     | 10 ++++------
>  2 files changed, 12 insertions(+), 9 deletions(-)
> 
> diff --git a/Documentation/driver-api/firmware/efi/index.rst b/Documentation/driver-api/firmware/efi/index.rst
> index 4fe8abba9fc6..5a6b6229592c 100644
> --- a/Documentation/driver-api/firmware/efi/index.rst
> +++ b/Documentation/driver-api/firmware/efi/index.rst
> @@ -1,11 +1,16 @@
>  .. SPDX-License-Identifier: GPL-2.0
>  
> -============
> -UEFI Support
> -============
> +====================================================
> +Unified Extensible Firmware Interface (UEFI) Support
> +====================================================
>  
>  UEFI stub library functions
>  ===========================
>  
>  .. kernel-doc:: drivers/firmware/efi/libstub/mem.c
>     :internal:
> +
> +UEFI Common Platform Error Record (CPER) functions
> +==================================================
> +
> +.. kernel-doc:: drivers/firmware/efi/cper.c
> diff --git a/drivers/firmware/efi/cper.c b/drivers/firmware/efi/cper.c
> index f8c8a15cd527..2785c8ea8ad8 100644
> --- a/drivers/firmware/efi/cper.c
> +++ b/drivers/firmware/efi/cper.c
> @@ -69,7 +69,7 @@ const char *cper_severity_str(unsigned int severity)
>  }
>  EXPORT_SYMBOL_GPL(cper_severity_str);
>  
> -/*
> +/**
>   * cper_print_bits - print strings for set bits
>   * @pfx: prefix for each line, including log level and prefix string
>   * @bits: bit mask
> @@ -106,18 +106,16 @@ void cper_print_bits(const char *pfx, unsigned int bits,
>  		printk("%s\n", buf);
>  }
>  
> -/*
> +/**
>   * cper_bits_to_str - return a string for set bits
>   * @buf: buffer to store the output string
>   * @buf_size: size of the output string buffer
>   * @bits: bit mask
>   * @strs: string array, indexed by bit position
>   * @strs_size: size of the string array: @strs
> - * @mask: a continuous bitmask used to detect the first valid bit of the
> - *        bitmap.
>   *
> - * Add to @buf the bitmask in hexadecimal. Then, for each set bit in @bits
> - * mask, add the corresponding string describing the bit in @strs to @buf.
> + * Add to @buf the bitmask in hexadecimal. Then, for each set bit in @bits,
> + * add the corresponding string describing the bit in @strs to @buf.
This is in wrong patch.  No point in introducing wrong docs to fix later.

>   */
>  char *cper_bits_to_str(char *buf, int buf_size, unsigned long bits,
>  		       const char * const strs[], unsigned int strs_size)