Re: [PATCH 5/6] docs/devel/qom: Remove usage of <code>

[Paolo Bonzini <pbonzini@redhat.com>]

On 03/10/20 04:54, Eduardo Habkost wrote:
> <code> is not valid reST syntax.
> 
> Function @argument references don't need additional markup, so
> just remove <code></code>.
> 
> Constants were changed to use reST ``code`` syntax
> 
> Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> ---
>  include/qom/object.h | 12 ++++++------
>  1 file changed, 6 insertions(+), 6 deletions(-)
> 
> diff --git a/include/qom/object.h b/include/qom/object.h
> index e738dfc6744..16c9bcdf3b0 100644
> --- a/include/qom/object.h
> +++ b/include/qom/object.h
> @@ -1256,7 +1256,7 @@ char *object_property_get_str(Object *obj, const char *name,
>   * Writes an object's canonical path to a property.
>   *
>   * If the link property was created with
> - * <code>OBJ_PROP_LINK_STRONG</code> bit, the old target object is
> + * ``OBJ_PROP_LINK_STRONG`` bit, the old target object is
>   * unreferenced, and a reference is added to the new target object.
>   *
>   * Returns: %true on success, %false on failure.
> @@ -1603,16 +1603,16 @@ void object_property_allow_set_link(const Object *obj, const char *name,
>   *
>   * Links form the graph in the object model.
>   *
> - * The <code>@check()</code> callback is invoked when
> + * The @check() callback is invoked when
>   * object_property_set_link() is called and can raise an error to prevent the
> - * link being set.  If <code>@check</code> is NULL, the property is read-only
> + * link being set.  If @check is NULL, the property is read-only
>   * and cannot be set.
>   *
>   * Ownership of the pointer that @child points to is transferred to the
> - * link property.  The reference count for <code>*@child</code> is
> + * link property.  The reference count for *@child is
>   * managed by the property from after the function returns till the
>   * property is deleted with object_property_del().  If the
> - * <code>@flags</code> <code>OBJ_PROP_LINK_STRONG</code> bit is set,
> + * @flags ``OBJ_PROP_LINK_STRONG`` bit is set,
>   * the reference count is decremented when the property is deleted or
>   * modified.

You can use % too in this case and in the first hunk above; there's
actually no difference between ``a`` and %a except the latter is
shorter.  Linux generally prefers %a, though kernel-doc also knows about
``a`` so that ``%x`` is interpreted correctly when the percent sign
should be a literal.

Apart from that.

Reviewed-by: Paolo Bonzini <pbonzini@redhat.com>

Paolo

>   *
> @@ -1823,7 +1823,7 @@ ObjectProperty *object_class_property_add_uint64_ptr(ObjectClass *klass,
>   * Add an alias for a property on an object.  This function will add a property
>   * of the same type as the forwarded property.
>   *
> - * The caller must ensure that <code>@target_obj</code> stays alive as long as
> + * The caller must ensure that @target_obj stays alive as long as
>   * this property exists.  In the case of a child object or an alias on the same
>   * object this will be the case.  For aliases to other objects the caller is
>   * responsible for taking a reference.
>