Re: RFC: Implementation of QMP documentation retrieval command

["Niteesh G. S." <niteesh.gs@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 4787 bytes --]

Hi Stefan,
On Tue, Jun 22, 2021 at 3:05 PM Stefan Hajnoczi <stefanha@redhat.com> 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:
>

I wanted to discuss the implementation of the documentation retrieval
command. Things like
1) The JSON schema we will be using to represent the documentation.
2) How will we be parsing documentation from the JSON files under qemu/qapi?
3) How will/where we'll be storing this parsed information?
And other questions which will have to be answered before proceeding to
implement this command.
4) Where to get data for autocomplete for the TUI?

- One easy way is to hardcode all available commands in the TUI
   autocomplete. But then we have to make sure to update the autocomplete
   list for TUI every time one new command gets added to QMP.


  ##
>   # @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?
>

Since this is just a prototype I have used plain text. But for the real
command
I expect something more structured since the comments I have seen in the
QAPI schema has some structure associated with them.
eg:
##
# @query-status:
#
# Query the run status of all VCPUs
#
# Returns: @StatusInfo reflecting all VCPUs
#
# Since:  0.14
#
# Example:
#
# -> { "execute": "query-status" }
# <- { "return": { "running": true,
#                  "singlestep": false,
#                  "status": "running" } }
#
##
We have the following structure
1) Command name
2) Documentation
3) Arguments (if any)
4) Return type with reference to non-primitive data types like
structs/enums etc
5) Since
6) Example

In the case of commands referring structures/enums and other non-primitive
data types
if possible we should also add their documentation along with the
documentation
for the command.
Yes, we could find out all the data types referenced by the current command
and
add them to the documentation if possible. This will make it easy for the
user.
If it isn't possible then we must allow to also query documentation related
to struct/enums etc.

  #
>   ##
>   { '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?
>
Not sure. I have gone through the parser code in qemu/scripts/qapi and also
have
seen the parser being used for documentation generation but I still don't
understand
the capabilities of the parser.


> 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.
>
Why will clients want to query the documentation for all commands? Even if
they do
won't that be an infrequent operation?
From the TUI perspective, I think it will be enough if we just have the
capability to
service one command at a time. We can also have the TUI cache the results
and
validate the cache during the greeting process by sending some kind of hash
to
notify if any documentation has changed or not.

>
> Do you see a need for wildcard queries where the client does not have
> the full command name? I guess the client has enough auto-completion
> information to search all commands on the client side, so maybe this
> functionality isn't necessary here?
>
One of my major questions(also mentioned above) is how will the client-side
get information regarding all the commands available in QMP? If we implement
a proper autocomplete feature then I don't think we will have to worry about
wildcard queries.


> Stefan
>

[-- Attachment #2: Type: text/html, Size: 9447 bytes --]