From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:47556) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1c4R7K-00039H-IN for qemu-devel@nongnu.org; Wed, 09 Nov 2016 06:32:35 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1c4R7G-0007oQ-Ie for qemu-devel@nongnu.org; Wed, 09 Nov 2016 06:32:34 -0500 Received: from mail-wm0-x235.google.com ([2a00:1450:400c:c09::235]:38384) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1c4R7G-0007o8-6u for qemu-devel@nongnu.org; Wed, 09 Nov 2016 06:32:30 -0500 Received: by mail-wm0-x235.google.com with SMTP id f82so236295448wmf.1 for ; Wed, 09 Nov 2016 03:32:30 -0800 (PST) Date: Wed, 9 Nov 2016 11:32:26 +0000 From: Stefan Hajnoczi Message-ID: <20161109113226.GD4682@stefanha-x1.localdomain> References: <20161107133045.GM5036@stefanha-x1.localdomain> <20161108162044.GE11274@stefanha-x1.localdomain> MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature"; boundary="KdquIMZPjGJQvRdI" Content-Disposition: inline In-Reply-To: Subject: Re: [Qemu-devel] Sphinx for QEMU docs? (and a doc-comment format question) List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: John Snow Cc: Peter Maydell , Paolo Bonzini , QEMU Developers , Stefan Hajnoczi --KdquIMZPjGJQvRdI Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Tue, Nov 08, 2016 at 11:24:21AM -0500, John Snow wrote: >=20 >=20 > On 11/08/2016 11:20 AM, Stefan Hajnoczi wrote: > > On Mon, Nov 07, 2016 at 05:52:37PM -0500, John Snow wrote: > > > On 11/07/2016 08:30 AM, Stefan Hajnoczi wrote: > > > > On Sat, Nov 05, 2016 at 06:42:23PM +0000, Peter Maydell wrote: > > > > > In particular I think we could: > > > > > * set up a framework for our in-tree docs/ which gives us a > > > > > place to put new docs (both for-users and for-developers) -- > > > > > I think having someplace to put things will reduce the barrier > > > > > to people writing useful new docs > > > > > * gradually convert the existing docs to rst > > > > > * use the sphinx extension features to pull in the doc-comments > > > > > we have been fairly consistently writing over the last few yea= rs > > > > > (for instance a converted version of docs/memory.txt could pull > > > > > in doc comments from memory.h; or we can just write simple > > > > > wrapper files like a "Bitmap operations" document that > > > > > displays the doc comments from bitops.h) > > > >=20 > > > > You are suggesting Sphinx for two different purposes: > > > >=20 > > > > 1. Formatting docs/ in HTML, PDF, etc. > > > >=20 > > > > 2. API documentation from doc comments. > > > >=20 > > > > It's a good idea for #1 since we can then publish automated builds = of > > > > the docs. They will be easy to view and link to in a web browser. > > > >=20 > > > > I'm not a fan of #2. QEMU is not a C library that people develop > > > > against and our APIs are not stable. There is no incentive for pre= tty > > > > doc comments. It might be cool to set it up once but things will > > > > deterioate again quickly because we don't actually need external API > > > > docs. > > > >=20 > > > > Instead of #2 we should focus on generating nice external QMP docs = for > > > > libvirt and other clients. That has a clear benefit. > > > >=20 > > > > Stefan > > > >=20 > > >=20 > > > I think that designating certain interfaces within QEMU as "Internal = API" > > > has some merit and are worth documenting for the sake of device/format > > > authors like Peter suggests. > >=20 > > To be clear, I'm not saying QEMU doesn't need doc comments. Every new > > function in include/*.h must have doc comments and many .c internal > > functions should too. > >=20 > > I'm just not enthusiastic about an effort to reformat doc comments and > > make them render to HTML, PDF, etc in a nice way because I don't think > > there's much payoff from doing that or maintaining it. > >=20 >=20 > OK, understood -- but if we are using a tool to syntax check the comment > formats, which helps us keep consistency and our docs up to date, we get = the > PDF/html outputs "for free." >=20 > I agree they're not particularly useful, but I consider them a harmless s= ide > effect. They might also help prove to new contributors that we're serious > about making QEMU easier to contribute to. >=20 > > > I think at a minimum, having _A_ standard approach cannot possibly be= *any* > > > worse than _NO_ standard approach. > >=20 > > People don't follow the standard format and markup syntax since that > > requires rendering and checking that the HTML, PDF, etc output looks > > correct before submitting patches. > >=20 >=20 > My only experience is with Doxygen, but that at least does have warnings = for > a great number of things. As long as you're passing the generation checks= , I > think there's not much need to actually check the html/pdf outputs except > periodically. >=20 > > I guess one solution is to extend checkpatch.pl to enforce that all doc > > comments follow a standard format. It still cannot check that @, #, etc > > are used in the right places but at least it can make sure that some > > standard layout is followed. > >=20 >=20 > This is the part that I'm hoping the generation tool can fulfill, assuming > it has generation warnings like Doxygen does. If we can check that new functions have doc comments and the comments follow the right format, then I'm happy. No doc comments -> error. Comments but not in doc format -> error. The check needs to be run before submitting patches and also by patchew. Otherwise those people who don't run the doc generator can fly under the radar ;-). Stefan --KdquIMZPjGJQvRdI Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQEcBAEBAgAGBQJYIwlKAAoJEJykq7OBq3PIjY4H/jcGTCGW3iesB0/sVG6Uq15I er212GGmoIaX/dewbvFhaB+GSHi8fg2+8BC0PQD0Tku/lv79HRl2ZfTfS/SdD4R7 rjJpweJLDsZgsviQdjPsrpT3euAMML+NgurPjsHAZ/TUFjWQbrAjOscBg+CRTKxH S4rSmTOKVLwaQzIGLrQkzHAXFGk2LVobnRYTUhOgOrIq1+DXLkuXRJ981TzvfQug uHZm/BoqXLr06gxmJ0IkRQzxbs9UXvkg21bAX/glHWY/CmkOPOKrXeybkZDS3jx7 J/riI61FSf78UykAKbIlta2DV8U5GpRS1Sn/rFV/+oXVwyr1MG4e9yKduSydisY= =qKpU -----END PGP SIGNATURE----- --KdquIMZPjGJQvRdI--