From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from [140.186.70.92] (port=39942 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OD42G-0004xo-Io for qemu-devel@nongnu.org; Fri, 14 May 2010 19:11:17 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1OD42E-0005Uv-Pf for qemu-devel@nongnu.org; Fri, 14 May 2010 19:11:16 -0400 Received: from mx1.redhat.com ([209.132.183.28]:29616) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1OD42E-0005Un-IG for qemu-devel@nongnu.org; Fri, 14 May 2010 19:11:14 -0400 Date: Fri, 14 May 2010 20:10:59 -0300 From: Luiz Capitulino Message-ID: <20100514201059.282481fa@redhat.com> In-Reply-To: <4BED8377.7040000@siemens.com> 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> 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: "bazulay@redhat.com" , "juzhang@redhat.com" , Avi Kivity , "armbru@redhat.com" , "qemu-devel@nongnu.org" 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. 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). 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.