Use kernel-doc to include clock API reference in
docs/devel/clocks.html. A few small change had to be made in
clock.h and qdev-clock.h to use the kernel-doc syntax.
Signed-off-by: Eduardo Habkost <ehabk...@redhat.com>
---
docs/devel/clocks.rst | 7 +++++++
include/hw/clock.h | 4 ++--
include/hw/qdev-clock.h | 28 ++++++++++++++++++----------
3 files changed, 27 insertions(+), 12 deletions(-)
diff --git a/docs/devel/clocks.rst b/docs/devel/clocks.rst
index e5da28e2111..9a390ad5df9 100644
--- a/docs/devel/clocks.rst
+++ b/docs/devel/clocks.rst
@@ -389,3 +389,10 @@ state.
Care should be taken not to use ``clock_update[_ns|_hz]()`` or
``clock_propagate()`` during the whole migration procedure because it
will trigger side effects to other devices in an unknown state.
+
+
+API Reference
+-------------
+
+.. kernel-doc:: include/hw/clock.h
+.. kernel-doc:: include/hw/qdev-clock.h
diff --git a/include/hw/clock.h b/include/hw/clock.h
index d357594df99..ffe8e99930a 100644
--- a/include/hw/clock.h
+++ b/include/hw/clock.h
@@ -43,7 +43,7 @@ typedef void ClockCallback(void *opaque);
#define CLOCK_PERIOD_TO_HZ(per) (((per) != 0) ? CLOCK_PERIOD_1SEC / (per) : 0u)
/**
- * Clock:
+ * struct Clock:
* @parent_obj: parent class
* @period: unsigned integer representing the period of the clock
* @canonical_path: clock path string cache (used for trace purpose)
@@ -56,7 +56,7 @@ typedef void ClockCallback(void *opaque);
struct Clock {
- /*< private >*/
+ /* private: */
Object parent_obj;
/* all fields are private and should not be modified directly */
diff --git a/include/hw/qdev-clock.h b/include/hw/qdev-clock.h
index 64ca4d266f2..3a00f798cab 100644
--- a/include/hw/qdev-clock.h
+++ b/include/hw/qdev-clock.h
@@ -22,7 +22,7 @@
* @name: the name of the clock (can't be NULL).
* @callback: optional callback to be called on update or NULL.
* @opaque: argument for the callback
- * @returns: a pointer to the newly added clock
+ * @return: a pointer to the newly added clock
*
* Add an input clock to device @dev as a clock named @name.
* This adds a child<> property.
@@ -35,7 +35,7 @@ Clock *qdev_init_clock_in(DeviceState *dev, const char *name,
* qdev_init_clock_out:
* @dev: the device to add an output clock to
* @name: the name of the clock (can't be NULL).
- * @returns: a pointer to the newly added clock
+ * @return: a pointer to the newly added clock
*
* Add an output clock to device @dev as a clock named @name.
* This adds a child<> property.
@@ -46,7 +46,7 @@ Clock *qdev_init_clock_out(DeviceState *dev, const char
*name);
* qdev_get_clock_in:
* @dev: the device which has the clock
* @name: the name of the clock (can't be NULL).
- * @returns: a pointer to the clock
+ * @return: a pointer to the clock
*
* Get the input clock @name from @dev or NULL if does not exist.
*/
@@ -56,7 +56,7 @@ Clock *qdev_get_clock_in(DeviceState *dev, const char *name);
* qdev_get_clock_out:
* @dev: the device which has the clock
* @name: the name of the clock (can't be NULL).
- * @returns: a pointer to the clock
+ * @return: a pointer to the clock
*
* Get the output clock @name from @dev or NULL if does not exist.
*/
@@ -81,7 +81,7 @@ void qdev_connect_clock_in(DeviceState *dev, const char
*name, Clock *source);
* @name: the name of the clock in @dev (can't be NULL)
* @alias_dev: the device to add the clock
* @alias_name: the name of the clock in @container
- * @returns: a pointer to the clock
+ * @return: a pointer to the clock
*
* Add a clock @alias_name in @alias_dev which is an alias of the clock @name
* in @dev. The direction _in_ or _out_ will the same as the original.
@@ -100,9 +100,9 @@ Clock *qdev_alias_clock(DeviceState *dev, const char *name,
void qdev_finalize_clocklist(DeviceState *dev);
/**
- * ClockPortInitElem:
+ * struct ClockPortInitElem:
* @name: name of the clock (can't be NULL)
- * @output: indicates whether the clock is input or output
+ * @is_output: indicates whether the clock is input or output
* @callback: for inputs, optional callback to be called on clock's update
* with device as opaque
* @offset: optional offset to store the ClockIn or ClockOut pointer in device
@@ -127,11 +127,11 @@ struct ClockPortInitElem {
}
/**
- * QDEV_CLOCK_(IN|OUT):
+ * QDEV_CLOCK_IN:
* @devstate: structure type. @dev argument of qdev_init_clocks below must be
* a pointer to that same type.
- * @field: a field in @_devstate (must be Clock*)
- * @callback: (for input only) callback (or NULL) to be called with the device
+ * @field: a field in @devstate (must be Clock*)
+ * @callback: callback (or NULL) to be called with the device
* state as argument
*
* The name of the clock will be derived from @field
@@ -139,6 +139,14 @@ struct ClockPortInitElem {
#define QDEV_CLOCK_IN(devstate, field, callback) \
QDEV_CLOCK(false, devstate, field, callback)
+/**
+ * QDEV_CLOCK_OUT:
+ * @devstate: structure type. @dev argument of qdev_init_clocks below must be
+ * a pointer to that same type.
+ * @field: a field in @devstate (must be Clock*)
+ *
+ * The name of the clock will be derived from @field
+ */
#define QDEV_CLOCK_OUT(devstate, field) \
QDEV_CLOCK(true, devstate, field, NULL)
--
2.26.2
