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

[Emanuele Giuseppe Esposito <eesposit@redhat.com>]

On 03/03/2021 17:43, Thomas Huth wrote:
> 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:

Apparently this does not appear with "make sphixdocs", only when doing a 
full build.

> 
> ../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?
> 

Thank you for spotting this. Will fix in v3.

Thank you,
Emanuele