[PATCH] docs/devel/clocks: Include API reference using kernel-doc

[Eduardo Habkost]

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 <ehabkost@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