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