Re: [PATCH v2 1/8] qobject: Include API docs in docs/devel/qobject.html

[Markus Armbruster]

Eduardo Habkost <ehabkost@redhat.com> writes:

> 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.
>   *

Educate me: what does DOC: do?

> 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)
>  {

Many lines of the form

  + * @foo: a foo

One of my reasons to dislike GTK-Doc.  Oh well, it's what we're using.