docs/devel/clocks: Include API reference using kernel-doc
PATCH 1/1 docs/devel/clocks: Include API reference using kernel-doc
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 <[email protected]>
--- docs/devel/clocks.rst | 7 +++++++ include/hw/clock.h | 4 ++-- include/hw/qdev-clock.h | 28 ++++++++++++++++++---------- 3 files changed, 27 insertions(+), 12 deletions(-)
docs/devel/clocks.rst +7 -0
@@ -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
include/hw/clock.h +2 -2
@@ -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 */
include/hw/qdev-clock.h +18 -10
@@ -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)
Signature · 1 line
2.26.2