From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from [140.186.70.92] (port=50356 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OE0HK-0007Hq-0i for qemu-devel@nongnu.org; Mon, 17 May 2010 09:22:43 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1OE0HI-000088-83 for qemu-devel@nongnu.org; Mon, 17 May 2010 09:22:41 -0400 Received: from mx1.redhat.com ([209.132.183.28]:8391) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1OE0HI-00007v-0U for qemu-devel@nongnu.org; Mon, 17 May 2010 09:22:40 -0400 Date: Mon, 17 May 2010 10:22:30 -0300 From: Luiz Capitulino Message-ID: <20100517102230.6ac03c3f@redhat.com> In-Reply-To: <4BEE5E84.2000503@web.de> References: <1273086712-29163-1-git-send-email-lcapitulino@redhat.com> <1273086712-29163-2-git-send-email-lcapitulino@redhat.com> <4BED7FDC.7030208@siemens.com> <4BED8202.5020309@redhat.com> <4BED8224.9030604@redhat.com> <4BED8377.7040000@siemens.com> <20100514201059.282481fa@redhat.com> <4BEE5E84.2000503@web.de> Mime-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Subject: [Qemu-devel] Re: [PATCH 1/2] QMP: Introduce commands doc List-Id: qemu-devel.nongnu.org List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: Jan Kiszka Cc: "qemu-devel@nongnu.org" , "bazulay@redhat.com" , "juzhang@redhat.com" , Avi Kivity , "armbru@redhat.com" On Sat, 15 May 2010 10:42:44 +0200 Jan Kiszka wrote: > Luiz Capitulino wrote: > > On Fri, 14 May 2010 19:08:07 +0200 > > Jan Kiszka wrote: > > > >> Avi Kivity wrote: > >>> On 05/14/2010 08:01 PM, Avi Kivity wrote: > >>>> On 05/14/2010 07:52 PM, Jan Kiszka wrote: > >>>>>> In order not to compromise QMP adoption and make users' life easier, > >>>>>> this commit adds a simple text documentation which fully describes > >>>>>> all QMP supported commands. > >>>>>> > >>>>>> This is not ideal for a number of reasons (harder to maintain, > >>>>>> text-only, etc) but does improve the current situation. > >>>>> Even if it's temporary - maintaining it in a separate file looks rather > >>>>> unhandy. > >>>>> > >>>>> Can't we generate the per-command documentation snippets also from > >>>>> qemu-monitor.hx and merge them with a header/footer into some text file? > >>>>> That .hx file is the one anyone adding/converting commands has to touch > >>>>> anyway. > >>>> If we do, then the generated documentation should be included in the > >>>> patch changelog for review. > >>>> > >>> I mean, a patch introducing or modifying a monitor command. > >> The snippets should be readable by themselves. I'm only proposing to > >> keep them in the central file, at the same location where the others > >> are. There is no difference compared to existing monitor commands, we > >> just add the third documentation snippet, this time for QMP. > > > > It's not only the snippets. We add a json type for each parameter, a > > more descriptive info and notes. Only QMP commands should be shown > > this way. > > Whatever its semantic is, technically it's a text block of a few lines > that has to be added somewhere. > > > > > I'm sure there's a way to hack the qemu's doc script to do all this, > > but the right solution is to move _everything_ to json and generate good, > > well formatted documentation from there (along with self-description). > > I'm not talking about The Right solution, I'm talking about a more handy > temporary setup. When do you plan to refactor the command documentation > that way? And how many commands will be touched in the meantime? It's something we would like to do ASAP, but there are a number of things we'll have to do first: bug fixes and some commands libvirt wants to use. > > Also, adapting things will take time and this will delay even more this > > doc to be merged, which is what I'm trying to avoid. > > > > I can provide you the patch for hxtool and Makefile (a few lines), and > I'm willing to split up the existing doc, just drop me a note. So > nothing needs to be delayed any further. I'd love that.