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

[Heinrich Schuchardt]

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: $_";

Best regards

Heinrich

> 
>>           *
>> -        * @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