Render existing doc comments at docs/devel/qobject.html.
Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
---
docs/devel/index.rst | 1 +
docs/devel/qobject.rst | 11 +++++++++
include/qapi/qmp/qnum.h | 4 +++-
include/qapi/qmp/qobject.h | 48 +++++++++++++++++++++++++-------------
qobject/qnum.c | 19 ++++++++++++---
5 files changed, 63 insertions(+), 20 deletions(-)
create mode 100644 docs/devel/qobject.rst
diff --git a/docs/devel/index.rst b/docs/devel/index.rst
index f10ed77e4c..1cb39a9384 100644
--- a/docs/devel/index.rst
+++ b/docs/devel/index.rst
@@ -35,3 +35,4 @@ Contents:
clocks
qom
block-coroutine-wrapper
+ qobject
diff --git a/docs/devel/qobject.rst b/docs/devel/qobject.rst
new file mode 100644
index 0000000000..4f192ced7c
--- /dev/null
+++ b/docs/devel/qobject.rst
@@ -0,0 +1,11 @@
+QObject API
+===========
+
+.. kernel-doc:: include/qapi/qmp/qobject.h
+
+QNum module
+-----------
+
+.. kernel-doc:: include/qapi/qmp/qnum.h
+
+.. kernel-doc:: qobject/qnum.c
diff --git a/include/qapi/qmp/qnum.h b/include/qapi/qmp/qnum.h
index bbae0a5ec8..25f4733efc 100644
--- a/include/qapi/qmp/qnum.h
+++ b/include/qapi/qmp/qnum.h
@@ -23,7 +23,9 @@ typedef enum {
QNUM_DOUBLE
} QNumKind;
-/*
+/**
+ * DOC:
+ *
* QNum encapsulates how our dialect of JSON fills in the blanks left
* by the JSON specification (RFC 8259) regarding numbers.
*
diff --git a/include/qapi/qmp/qobject.h b/include/qapi/qmp/qobject.h
index fcfd549220..bdc33bdb65 100644
--- a/include/qapi/qmp/qobject.h
+++ b/include/qapi/qmp/qobject.h
@@ -1,5 +1,5 @@
/*
- * QEMU Object Model.
+ * QObject API
*
* Based on ideas by Avi Kivity <avi@redhat.com>
*
@@ -10,24 +10,31 @@
*
* This work is licensed under the terms of the GNU LGPL, version 2.1 or later.
* See the COPYING.LIB file in the top-level directory.
+ */
+
+/**
+ * DOC: QObject Reference Counts Terminology
*
- * QObject Reference Counts Terminology
- * ------------------------------------
+ * Returning references
+ * --------------------
*
- * - Returning references: A function that returns an object may
- * return it as either a weak or a strong reference. If the
- * reference is strong, you are responsible for calling
- * qobject_unref() on the reference when you are done.
+ * A function that returns an object may return it as either a
+ * weak or a strong reference. If the reference is strong, you
+ * are responsible for calling qobject_unref() on the reference
+ * when you are done.
*
- * If the reference is weak, the owner of the reference may free it at
- * any time in the future. Before storing the reference anywhere, you
- * should call qobject_ref() to make the reference strong.
+ * If the reference is weak, the owner of the reference may free it at
+ * any time in the future. Before storing the reference anywhere, you
+ * should call qobject_ref() to make the reference strong.
*
- * - Transferring ownership: when you transfer ownership of a reference
- * by calling a function, you are no longer responsible for calling
- * qobject_unref() when the reference is no longer needed. In other words,
- * when the function returns you must behave as if the reference to the
- * passed object was weak.
+ * Transferring ownership
+ * ----------------------
+ *
+ * When you transfer ownership of a reference by calling a
+ * function, you are no longer responsible for calling
+ * qobject_unref() when the reference is no longer needed. In
+ * other words, when the function returns you must behave as if
+ * the reference to the passed object was weak.
*/
#ifndef QOBJECT_H
#define QOBJECT_H
@@ -81,6 +88,8 @@ static inline void qobject_ref_impl(QObject *obj)
/**
* qobject_is_equal(): Return whether the two objects are equal.
+ * @x: QObject pointer
+ * @y: QObject pointer
*
* Any of the pointers may be NULL; return true if both are. Always
* return false if only one is (therefore a QNull object is not
@@ -90,6 +99,7 @@ bool qobject_is_equal(const QObject *x, const QObject *y);
/**
* qobject_destroy(): Free resources used by the object
+ * @obj: QObject pointer
*/
void qobject_destroy(QObject *obj);
@@ -103,6 +113,7 @@ static inline void qobject_unref_impl(QObject *obj)
/**
* qobject_ref(): Increment QObject's reference count
+ * @obj: QObject pointer
*
* Returns: the same @obj. The type of @obj will be propagated to the
* return type.
@@ -115,12 +126,14 @@ static inline void qobject_unref_impl(QObject *obj)
/**
* qobject_unref(): Decrement QObject's reference count, deallocate
- * when it reaches zero
+ * when it reaches zero
+ * @obj: QObject pointer
*/
#define qobject_unref(obj) qobject_unref_impl(QOBJECT(obj))
/**
* qobject_type(): Return the QObject's type
+ * @obj: QObject pointer
*/
static inline QType qobject_type(const QObject *obj)
{
@@ -130,6 +143,9 @@ static inline QType qobject_type(const QObject *obj)
/**
* qobject_check_type(): Helper function for the qobject_to() macro.
+ * @obj: QObject pointer
+ * @type: Expected type of QObject
+ *
* Return @obj, but only if @obj is not NULL and @type is equal to
* @obj's type. Return NULL otherwise.
*/
diff --git a/qobject/qnum.c b/qobject/qnum.c
index 7012fc57f2..017c8aa739 100644
--- a/qobject/qnum.c
+++ b/qobject/qnum.c
@@ -17,6 +17,7 @@
/**
* qnum_from_int(): Create a new QNum from an int64_t
+ * @value: int64_t value
*
* Return strong reference.
*/
@@ -33,6 +34,7 @@ QNum *qnum_from_int(int64_t value)
/**
* qnum_from_uint(): Create a new QNum from an uint64_t
+ * @value: uint64_t value
*
* Return strong reference.
*/
@@ -49,6 +51,7 @@ QNum *qnum_from_uint(uint64_t value)
/**
* qnum_from_double(): Create a new QNum from a double
+ * @value: double value
*
* Return strong reference.
*/
@@ -65,6 +68,8 @@ QNum *qnum_from_double(double value)
/**
* qnum_get_try_int(): Get an integer representation of the number
+ * @qn: QNum object
+ * @val: pointer to value
*
* Return true on success.
*/
@@ -90,6 +95,7 @@ bool qnum_get_try_int(const QNum *qn, int64_t *val)
/**
* qnum_get_int(): Get an integer representation of the number
+ * @qn: QNum object
*
* assert() on failure.
*/
@@ -102,7 +108,9 @@ int64_t qnum_get_int(const QNum *qn)
}
/**
- * qnum_get_uint(): Get an unsigned integer from the number
+ * qnum_value_get_try_uint(): Get an unsigned integer from the number
+ * @qn: QNum object
+ * @val: pointer to value
*
* Return true on success.
*/
@@ -128,6 +136,7 @@ bool qnum_get_try_uint(const QNum *qn, uint64_t *val)
/**
* qnum_get_uint(): Get an unsigned integer from the number
+ * @qn: QNum object
*
* assert() on failure.
*/
@@ -141,6 +150,7 @@ uint64_t qnum_get_uint(const QNum *qn)
/**
* qnum_get_double(): Get a float representation of the number
+ * @qn: QNum object
*
* qnum_get_double() loses precision for integers beyond 53 bits.
*/
@@ -200,6 +210,8 @@ char *qnum_to_string(QNum *qn)
/**
* qnum_is_equal(): Test whether the two QNums are equal
+ * @x: QNum object
+ * @y: QNum object
*
* Negative integers are never considered equal to unsigned integers,
* but positive integers in the range [0, INT64_MAX] are considered
@@ -253,8 +265,9 @@ bool qnum_is_equal(const QObject *x, const QObject *y)
}
/**
- * qnum_destroy_obj(): Free all memory allocated by a
- * QNum object
+ * qnum_destroy_obj(): Free all memory allocated by a QNum object
+ *
+ * @obj: QNum object to be destroyed
*/
void qnum_destroy_obj(QObject *obj)
{
--
2.28.0