Re: [PATCH 1/9] doc: add include/dm/uclass.h to the HTML documentation
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
---
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 00..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
Patrick
Re: [PATCH 1/9] doc: add include/dm/uclass.h to the HTML documentation
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
---
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 00..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.
Reviewed-by: Heinrich Schuchardt
*
- * extern UCLASS_DRIVER(clk);
- *
- * struct uclass_driver *drvs[] = {
- * DM_UCLASS_DRIVER_REF(clk),
- * };
+ * extern UCLASS_DRIVER(clk);
+ * struct uclass_driver *drvs[] = {
+ * DM_UCLASS_DRIVER_REF(clk),
+ * };
*
* @_name: Name of the uclass_driver. This must be a valid C identifier, used
by
*the linker_list.
- * @returns struct uclass_driver * for the uclass driver
+ * Return: struct uclass_driver * for the uclass driver
*/
#define DM_UCLASS_DRIVER_REF(_name) \
ll_entry_ref(struct uclass_driver, _name, uclass_driver)
@@ -145,8 +144,8 @@ struct uclass_driver {
/**
* uclass_get_priv() - Get the private data for a uclass
*
- * @uc Uclass to check
- * @return private data, or NULL if none
+ * @uc:Uclass to check
+ * Return: private data, or NULL if none
*/
void *uclass_get_priv(const struct uclass *uc);
@@ -159,8 +158,8 @@ void *uclass_get_priv(const struct uclass *uc);
*
* @key: ID to look up
* @ucp: Returns pointer to uclass (there is only one per ID)
- * @return 0 if OK, -EDEADLK if driver model is not yet inited, other -ve on
- * other error
+ * Return: 0 if OK, -EDEADLK if driver model is not yet inited, other -ve on
+ * other error
*/
int uclass_get(enum uclass_id key, struct uclass **ucp);
@@ -168,16 +167,16 @@ int uclass_get(enum uclass_id key, struct uclass **ucp);
* uclass_get_name() - Get the name of a uclass driver
*
* @id: ID to look up
- * @returns the name of the uclass driver for that ID, or NULL if none
+ * Return: the name of the uclass driver for that ID, or NULL if none
*/
const char *uclass_get_name(enum uclass_id id);
/**
- * uclass_get_by_name() - Look up a uclass by its driver name
+ * uclass_get_by_name_len() - Look up a uclass by its partial driver name
*
* @name: Name to look up
- * @len: Length of name
- * @returns the associated uclass ID, or UCLASS_INVALID if not found
+ * @len: Length of the partial name
+ * Return: the associated uclass ID, or UCLASS_INVALID if not found
*/
enum uclass_id uclass_get_by_name_len(const char *name, int len);
@@ -185,7 +184,7 @@ enum uclass_id uclass_get_by_name_len(const char *name, int
len);
* uclass_get_by_name() - Look up a uclass by its driver name
*
* @name: Name to look up
- * @returns the associated uclass ID, or UCLASS_INVALID if not found
+ * Return: the associated uclass ID, or UCLASS_INVALID if not found
*/
enum uclass_id uclass_get_by_name(const char *name);
@@ -197,7 +196,7 @@ enum uclass_id uclass_get_by_name(const char *name);
* @id: ID to look up
* @index: Device number within that uclass (0=first)
* @devp: Returns pointer to device (there is only one per for each ID)
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
*/
int uclass_get_device(enum uclass_id id, int index, struct udevice **devp);
@@ -211,7 +210,7 @@ int uclass_get_device(enum uclass_id id, int index, struct
udevice **devp);
* @id: ID to look up
* @name: name of a device to get
* @devp: Returns pointer to device (the first one with the name)
- * @return 0 if OK, -ve on error
+ * Return
[PATCH 1/9] doc: add include/dm/uclass.h to the HTML documentation
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
---
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 00..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: ::
*
- * extern UCLASS_DRIVER(clk);
- *
- * struct uclass_driver *drvs[] = {
- * DM_UCLASS_DRIVER_REF(clk),
- * };
+ * extern UCLASS_DRIVER(clk);
+ * struct uclass_driver *drvs[] = {
+ * DM_UCLASS_DRIVER_REF(clk),
+ * };
*
* @_name: Name of the uclass_driver. This must be a valid C identifier, used
by
* the linker_list.
- * @returns struct uclass_driver * for the uclass driver
+ * Return: struct uclass_driver * for the uclass driver
*/
#define DM_UCLASS_DRIVER_REF(_name)\
ll_entry_ref(struct uclass_driver, _name, uclass_driver)
@@ -145,8 +144,8 @@ struct uclass_driver {
/**
* uclass_get_priv() - Get the private data for a uclass
*
- * @uc Uclass to check
- * @return private data, or NULL if none
+ * @uc:Uclass to check
+ * Return: private data, or NULL if none
*/
void *uclass_get_priv(const struct uclass *uc);
@@ -159,8 +158,8 @@ void *uclass_get_priv(const struct uclass *uc);
*
* @key: ID to look up
* @ucp: Returns pointer to uclass (there is only one per ID)
- * @return 0 if OK, -EDEADLK if driver model is not yet inited, other -ve on
- * other error
+ * Return: 0 if OK, -EDEADLK if driver model is not yet inited, other -ve on
+ * other error
*/
int uclass_get(enum uclass_id key, struct uclass **ucp);
@@ -168,16 +167,16 @@ int uclass_get(enum uclass_id key, struct uclass **ucp);
* uclass_get_name() - Get the name of a uclass driver
*
* @id: ID to look up
- * @returns the name of the uclass driver for that ID, or NULL if none
+ * Return: the name of the uclass driver for that ID, or NULL if none
*/
const char *uclass_get_name(enum uclass_id id);
/**
- * uclass_get_by_name() - Look up a uclass by its driver name
+ * uclass_get_by_name_len() - Look up a uclass by its partial driver name
*
* @name: Name to look up
- * @len: Length of name
- * @returns the associated uclass ID, or UCLASS_INVALID if not found
+ * @len: Length of the partial name
+ * Return: the associated uclass ID, or UCLASS_INVALID if not found
*/
enum uclass_id uclass_get_by_name_len(const char *name, int len);
@@ -185,7 +184,7 @@ enum uclass_id uclass_get_by_name_len(const char *name, int
len);
* uclass_get_by_name() - Look up a uclass by its driver name
*
* @name: Name to look up
- * @returns the associated uclass ID, or UCLASS_INVALID if not found
+ * Return: the associated uclass ID, or UCLASS_INVALID if not found
*/
enum uclass_id uclass_get_by_name(const char *name);
@@ -197,7 +196,7 @@ enum uclass_id uclass_get_by_name(const char *name);
* @id: ID to look up
* @index: Device number within that uclass (0=first)
* @devp: Returns pointer to device (there is only one per for each ID)
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
*/
int uclass_get_device(enum uclass_id id, int index, struct udevice **devp);
@@ -211,7 +210,7 @@ int uclass_get_device(enum uclass_id id, int index, struct
udevice **devp);
* @id: ID to look up
* @name: name of a device to get
* @devp: Returns pointer to device (the first one with the name)
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
*/
int uclass_get_device_by_name(enum uclass_id id, const char *name,
struct udevice **devp);
@@ -228,7 +227,7 @@ int uclass_get_device_by_name(enum u
