Re: RFC: Implementation of QMP documentation retrieval command

[Vladimir Sementsov-Ogievskiy]

22.06.2021 13:26, Daniel P. Berrangé wrote:

There's a more fundamental question about structure here too.
The documentation is not a arbitrary block of text. It contains
specific data items for individual parameters, and return
type, along with version number annotation too.

If we're returning a single string, then the caller needs to
know how to parser the current docs structure we're using
for commands. Right now that's an internal only format, and
I'm not sure we want to expose that as an ABI to consumers
of QEMU. So quite possibly we need to return structured
data instead

eg potentially we need

    { 'struct': 'CommandDocumentation',
      'data': {'name': 'str',
               'summary': 'str'
               'description: 'str'
              'parameters': ['str'],
              'return': str,
              'since': str,
              'notes': str,
              'example':str,
             } }

If make 'since' a separate field, it make sense to report appropriate 'since' 
for each parameter, so parameters would not be a simple list of strings.. Not 
saying of types of parameters.

--
Best regards,
Vladimir