Re: RFC: Implementation of QMP documentation retrieval command

[Daniel P . Berrangé]

On Tue, Jun 22, 2021 at 10:35:47AM +0100, Stefan Hajnoczi wrote:
> On Mon, Jun 21, 2021 at 11:56:30PM +0530, Niteesh G. S. wrote:
> > TLDR: The goal of this mail wasn't to review the dummy command I had posted
> > but
> > rather start a discussion regarding the implementation of the QMP
> > documentation
> > retrieval command for the TUI.
> 
> It's not clear to me what exactly you wanted to discuss. Here is the QMP
> schema from the commit you linked. It's something concrete that we can
> discuss:
> 
>   ##
>   # @CommandDocumentation:
>   #
>   # A object representing documentation for a command.
>   #
>   # @name: Command name
>   #
>   # @doc: A string containing the documentation.
> 
> Is @doc in some kind of markup or plain text?

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,
             } }

> 
>   #
>   ##
>   { 'struct': 'CommandDocumentation',
>     'data': {'name': 'str', 'doc': 'str'} }
> 
>   ##
>   # @query-cmd-doc:
>   #
>   # (A simple *prototype* implementation)
>   # Command query-cmd-doc will return the documentation for the command
>   # specified. This will help QMP clients currently the AQMP TUI to show
>   # documentation related to a specific command.
>   #
>   # @command-name: The command name to query documentation for
>   #
>   # Returns: A @CommandDocumentation object containing the documentation.
>   #
>   # Since: TODO: Add a number
>   ##
>   { 'command': 'query-cmd-doc',
>     'data': { 'command-name': 'str' },
>     'returns': 'CommandDocumentation' }
> 
> Is there a way to retrieve struct/enum/etc documentation?
> 
> Do you see a need to query multiple items of documentation in a single
> command? A single item query command can become a performance bottleneck
> if the clients wants to query the documentation for all commands, for
> example. This can be solved by making the the return value an array and
> allowing multiple commands to be queried at once.

If you want batch querying, then it needs to recursively return all
the struct/enum docs related to the commands parameters/return values
too.

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|