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 <[email protected]> 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 <[email protected]> --- 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-values [2] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/linux/phylink.h#n81+ * -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
