Re: [PATCH v2] libqos/qgraph: format qgraph comments for sphinx documentation

[Thomas Huth]

On 25/02/2021 13.22, Emanuele Giuseppe Esposito wrote:
> Change documentation style and fix minor typos in tests/qtest/libqos/qgraph.h
> to automatically generate sphinx documentation in docs/devel/qgraph.rst
>
> The mechanism explanation that once was in qgraph.h is now moved to qgraph.rst
>
> There is no functional change intended.
>
> v2:
> - qgraph link visible in docs/devel/index but not in docs/index, since it is
> a subsection of qtest.
>
> Signed-off-by: Emanuele Giuseppe Esposito <eesposit@redhat.com>
> ---
>   MAINTAINERS                 |   1 +
>   docs/devel/index.rst        |   1 +
>   docs/devel/qgraph.rst       | 261 ++++++++++++++++++++++++++++++
>   docs/devel/qtest.rst        |   8 +
>   tests/qtest/libqos/qgraph.h | 308 ++++++------------------------------
>   5 files changed, 320 insertions(+), 259 deletions(-)
>   create mode 100644 docs/devel/qgraph.rst

I'm getting a bunch of warnings after applying this patch:

../tests/qtest/libqos/qgraph.h:53: warning: cannot understand function 
prototype: 'struct QOSGraphEdgeOptions '
../tests/qtest/libqos/qgraph.h:93: warning: cannot understand function 
prototype: 'struct QOSGraphTestOptions '
../tests/qtest/libqos/qgraph.h:138: warning: cannot understand function 
prototype: 'struct QOSGraphObject '
../tests/qtest/libqos/qgraph.h:218: warning: Function parameter or member 
'opts' not described in 'qos_node_create_machine_args'
../tests/qtest/libqos/qgraph.h:218: warning: Excess function parameter 'pts' 
description in 'qos_node_create_machine_args'

Any chance to fix them first?

 Thomas