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

[Simon Glass]

Hi Heinrich,

On Tue, 15 Aug 2023 at 09:18, Heinrich Schuchardt
<heinrich.schuchardt at canonical.com> wrote:
>
>
>
> On 8/15/23 16:44, Simon Glass wrote:
> > 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.
>
> Thanks for reviewing.
>
> 'make htmldocs' does not like parentheses here:
>
> Incorrect use of kernel-doc format:
> * @get_info(): Get ...
> Incorrect use of kernel-doc format:
> * @get_info() - Get ...
>
> We are using code from the kernel.org. We would have to change that
> upstream first:
>
> scripts/kernel-doc:2325:
> print STDERR "Incorrect use of kernel-doc format: $_";

OK thank you, I will send an mail about it.

Do you think you could base your part on [1], since I changed the same
file? It is available at u-boot-dm/methb-working

Regards,
Simon

[1] https://patchwork.ozlabs.org/project/uboot/list/?series=368613