[PATCH 1/1] doc: add partition API to HTML documentation

[Simon Glass]

Hi Heinrich,

On Tue, 15 Aug 2023 at 04:32, Heinrich Schuchardt
<heinrich.schuchardt at canonical.com> wrote:
>
> * Convert comments in part.h to Sphinx style.
> * Create documentation page for the partition API.
> * Add the partition API page to the API index page.
>
> Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt at canonical.com>
> ---
>  doc/api/index.rst |   1 +
>  doc/api/part.rst  |   6 ++
>  include/part.h    | 210 ++++++++++++++++++++++++----------------------
>  3 files changed, 119 insertions(+), 98 deletions(-)
>  create mode 100644 doc/api/part.rst

Reviewed-by: Simon Glass <sjg at chromium.org>

Q below

>
> diff --git a/doc/api/index.rst b/doc/api/index.rst
> index a9338cfef9..3a80ae0635 100644
> --- a/doc/api/index.rst
> +++ b/doc/api/index.rst
> @@ -15,6 +15,7 @@ U-Boot API documentation
>     lmb
>     logging
>     nvmem
> +   part
>     pinctrl
>     rng
>     sandbox
> diff --git a/doc/api/part.rst b/doc/api/part.rst
> new file mode 100644
> index 0000000000..d1df1d8494
> --- /dev/null
> +++ b/doc/api/part.rst
> @@ -0,0 +1,6 @@
> +.. SPDX-License-Identifier: GPL-2.0+
> +
> +Partition API
> +=============
> +[..]

> +/**
> + * struct part_driver - partition driver
> + */
>  struct part_driver {
> +       /** @name:      partition name */
>         const char *name;
> +       /** @part_type: (MBR) partition type */
>         int part_type;
> -       const int max_entries;  /* maximum number of entries to search */
> -
> +       /** @max_entries:       maximum number of partition table entries */
> +       const int max_entries;
>         /**
> -        * get_info() - Get information about a partition
> +        * @get_info:           Get information about a partition

Are we not allowed the () at end? I much prefer brackets as they show
it is a function.

>          *
> -        * @dev_desc:   Block device descriptor
> -        * @part:       Partition number (1 = first)
> -        * @info:       Returns partition information
> +        * @get_info.dev_desc:  Block device descriptor
> +        * @get_info.part:      Partition number (1 = first)
> +        * @get_info.info:      Returns partition information
>          */
>         int (*get_info)(struct blk_desc *dev_desc, int part,
>                         struct disk_partition *info);
[..]

Regards,
Simon