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

[Eduardo Habkost]

CCing Peter, Sphinx documentation machinery maintainer.

On Thu, Nov 19, 2020 at 10:37:22AM +0100, Markus Armbruster wrote:
> Eduardo Habkost <ehabkost@redhat.com> writes:
> 
> > Render existing doc comments at docs/devel/qobject.html.
> >
> > Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> > ---
[...]
> >  /**
> > - * 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

I hate them too.

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

It's not gtk-doc.  It's kernel-doc who generates warnings
if some parameters are not documented, and maybe we should
silence them.

-- 
Eduardo