[PATCH 1/9] doc: add include/dm/uclass.h to the HTML documentation

[Patrick DELAUNAY]

Hi Heinrich,

On 1/15/22 9:24 AM, Heinrich Schuchardt wrote:
> On 1/12/22 10:53, Patrick Delaunay wrote:
>> Correct Sphinx style comments in include/dm/uclass.h
>> and add the driver model UCLASS API to the HTML documentation.
>>
>> Signed-off-by: Patrick Delaunay <patrick.delaunay at foss.st.com>
>> ---
>>
>>   doc/api/dm.rst      |  9 ++++++
>>   doc/api/index.rst   |  1 +
>>   include/dm/uclass.h | 75 ++++++++++++++++++++++-----------------------
>>   3 files changed, 47 insertions(+), 38 deletions(-)
>>   create mode 100644 doc/api/dm.rst
>>
>> diff --git a/doc/api/dm.rst b/doc/api/dm.rst
>> new file mode 100644
>> index 0000000000..edce25da51
>> --- /dev/null
>> +++ b/doc/api/dm.rst
>> @@ -0,0 +1,9 @@
>> +.. SPDX-License-Identifier: GPL-2.0+
>> +
>> +Driver Model
>> +============
>> +
>> +Uclass and Driver
>> +-----------------
>> +
>> +.. kernel-doc:: include/dm/uclass.h
>> diff --git a/doc/api/index.rst b/doc/api/index.rst
>> index 806c7385a6..3f36174167 100644
>> --- a/doc/api/index.rst
>> +++ b/doc/api/index.rst
>> @@ -7,6 +7,7 @@ U-Boot API documentation
>>      :maxdepth: 2
>>
>>      dfu
>> +   dm
>>      efi
>>      getopt
>>      linker_lists
>> diff --git a/include/dm/uclass.h b/include/dm/uclass.h
>> index f1fd2ba246..a12a872d94 100644
>> --- a/include/dm/uclass.h
>> +++ b/include/dm/uclass.h
>> @@ -84,7 +84,7 @@ struct udevice;
>>    * its children. If non-zero this is the size of this data, to be 
>> allocated
>>    * in the child device's parent_plat pointer. This value is only 
>> used as
>>    * a fallback if this member is 0 in the driver.
>> - * @flags: Flags for this uclass (DM_UC_...)
>> + * @flags: Flags for this uclass ``(DM_UC_...)``
>>    */
>>   struct uclass_driver {
>>       const char *name;
>> @@ -127,17 +127,16 @@ struct uclass_driver {
>>    * build time. Before this is used, an extern UCLASS_DRIVER() must 
>> have been
>>    * declared.
>>    *
>> - * For example:
>> + * For example: ::
>
> Nits:
> "For example::" has the same effect. I will change this when merging.
>
ok.

https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#literal-blocks

I miss the 'Fully minimized form:' or when I test the html output

I let a space before the Literal Blocks => "Paragraph ::"

FYI: I do the same issue in several location I think.


> Reviewed-by: Heinrich Schuchardt <xypron.glpk at gmx.de>
>
>>

Patrick