On 9/24/21 7:51 AM, Sean Anderson wrote:
On 9/24/21 1:27 AM, Alexandre Ghiti wrote:
On Thu, Sep 23, 2021 at 11:12 AM Heinrich Schuchardt heinrich.schuchardt@canonical.com wrote:
Complete the Sphinx documentation in include/sysreset.h Add the include to the generated HTML documentation of the U-Boot API.
Signed-off-by: Heinrich Schuchardt heinrich.schuchardt@canonical.com
doc/api/index.rst | 1 + doc/api/sysreset.rst | 7 ++++++ include/sysreset.h | 53 ++++++++++++++++++++++++++++---------------- 3 files changed, 42 insertions(+), 19 deletions(-) create mode 100644 doc/api/sysreset.rst
diff --git a/doc/api/index.rst b/doc/api/index.rst index ea02aa5715..281d1dca96 100644 --- a/doc/api/index.rst +++ b/doc/api/index.rst @@ -15,5 +15,6 @@ U-Boot API documentation rng sandbox serial + sysreset timer unicode diff --git a/doc/api/sysreset.rst b/doc/api/sysreset.rst new file mode 100644 index 0000000000..a51b06c387 --- /dev/null +++ b/doc/api/sysreset.rst @@ -0,0 +1,7 @@ +.. SPDX-License-Identifier: GPL-2.0+
+System reset +============
+.. kernel-doc:: include/sysreset.h + :internal: diff --git a/include/sysreset.h b/include/sysreset.h index 701e4f5c86..e8411f9664 100644 --- a/include/sysreset.h +++ b/include/sysreset.h @@ -9,43 +9,55 @@
struct udevice;
+/**
- enum systreset_t - system reset types
- */
enum sysreset_t { - SYSRESET_WARM, /* Reset CPU, keep GPIOs active */ - SYSRESET_COLD, /* Reset CPU and GPIOs */ - SYSRESET_POWER, /* Reset PMIC (remove and restore power) */ - SYSRESET_POWER_OFF, /* Turn off power */
+ /** @SYSRESET_WARM: reset CPU, keep GPIOs active */ + SYSRESET_WARM, + /** @SYSRESET_COLD: reset CPU and GPIOs */ + SYSRESET_COLD, + /** @SYSRESET_POWER: reset PMIC (remove and restore power) */ + SYSRESET_POWER, + /** @SYSRESET_POWER_OFF: turn off power */ + SYSRESET_POWER_OFF, + /** @SYSRESET_COUNT: number of available reset types */ SYSRESET_COUNT, };
+/**
- struct sysreset_ops - operations of system reset drivers
- */
struct sysreset_ops { /** - * request() - request a sysreset of the given type + * @request: request a sysreset of the given type * * Note that this function may return before the reset takes effect. * + * @dev: Device to be used for system reset * @type: Reset type to request - * @return -EINPROGRESS if the reset has been started and - * will complete soon, -EPROTONOSUPPORT if not supported - * by this device, 0 if the reset has already happened - * (in which case this method will not actually return) + * Return:
Shouldn't this be @Return (and for all others below too)? Otherwise the output of "Result" is not bold. And I also noticed that all parameters and return descriptions appear on the same line: include/dm/pinctrl.h adds newlines between each parameter description and then every argument has its own line.
The issue here is that the recommended style [1] does not work well for struct members. To get things looking reasonably you have to mess with the formatting a bit. An alternative is to put a short description in the struct itself, and add a longer version in ifdef'd out "virtual" functions, such as in [2].
We should stick with [1]. If the formatting is not correct, it is a problem with the Sphinx C-domain.
We inherited doc/sphinx/parse-headers.pl from Linux. I guess this is the code which needs to be fixed.
Best regards
Heinrich
--Sean
[1] https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#return-valu...
[2] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/incl...
+ * -EINPROGRESS if the reset has been started and + * will complete soon, -EPROTONOSUPPORT if not supported + * by this device, 0 if the reset has already happened + * (in which case this method will not actually return) */ int (*request)(struct udevice *dev, enum sysreset_t type); /** - * get_status() - get printable reset status information + * @get_status: get printable reset status information * * @dev: Device to check * @buf: Buffer to receive the textual reset information * @size: Size of the passed buffer - * @return 0 if OK, -ve on error + * Return: 0 if OK, -ve on error */ int (*get_status)(struct udevice *dev, char *buf, int size);
/** - * get_last() - get information on the last reset + * @get_last: get information on the last reset * * @dev: Device to check - * @return last reset state (enum sysreset_t) or -ve error + * Return: last reset state (enum :enum:`sysreset_t`) or -ve error */ int (*get_last)(struct udevice *dev); }; @@ -55,8 +67,9 @@ struct sysreset_ops { /** * sysreset_request() - request a sysreset *
- @dev: Device to be used for system reset
* @type: Reset type to request
- @return 0 if OK, -EPROTONOSUPPORT if not supported by this device
- Return: 0 if OK, -EPROTONOSUPPORT if not supported by this
device */ int sysreset_request(struct udevice *dev, enum sysreset_t type);
@@ -66,7 +79,7 @@ int sysreset_request(struct udevice *dev, enum sysreset_t type); * @dev: Device to check * @buf: Buffer to receive the textual reset information * @size: Size of the passed buffer
- @return 0 if OK, -ve on error
- Return: 0 if OK, -ve on error
*/ int sysreset_get_status(struct udevice *dev, char *buf, int size);
@@ -74,7 +87,7 @@ int sysreset_get_status(struct udevice *dev, char *buf, int size); * sysreset_get_last() - get information on the last reset * * @dev: Device to check
- @return last reset state (enum sysreset_t) or -ve error
- Return: last reset state (enum sysreset_t) or -ve error
*/ int sysreset_get_last(struct udevice *dev);
@@ -88,7 +101,7 @@ int sysreset_get_last(struct udevice *dev); * If this function fails to reset, it will display a message and halt * * @type: Reset type to request
- @return -EINPROGRESS if a reset is in progress, -ENOSYS if not
available
- Return: -EINPROGRESS if a reset is in progress, -ENOSYS if
not available */ int sysreset_walk(enum sysreset_t type);
@@ -101,7 +114,7 @@ int sysreset_walk(enum sysreset_t type); * * If no device prives the information, this function returns -ENOENT *
- @return last reset state (enum sysreset_t) or -ve error
- Return: last reset state (enum sysreset_t) or -ve error
*/ int sysreset_get_last_walk(void);
@@ -110,6 +123,8 @@ int sysreset_get_last_walk(void); * * This calls sysreset_walk(). If it returns, indicating that reset is not * supported, it prints a message and halts.
- @type: Reset type to request
*/ void sysreset_walk_halt(enum sysreset_t type);
-- 2.32.0