Re: RFC: Implementation of QMP documentation retrieval command

[Stefan Hajnoczi <stefanha@redhat.com>]

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

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?

  #
  ##
  { '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.

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?

Stefan

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]