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