From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:33415) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VsYBz-0004sj-U0 for qemu-devel@nongnu.org; Mon, 16 Dec 2013 08:26:45 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1VsYBu-0004Sz-KC for qemu-devel@nongnu.org; Mon, 16 Dec 2013 08:26:39 -0500 Received: from cantor2.suse.de ([195.135.220.15]:39030 helo=mx2.suse.de) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VsYBu-0004Sm-DX for qemu-devel@nongnu.org; Mon, 16 Dec 2013 08:26:34 -0500 Message-ID: <52AEFF86.9070106@suse.de> Date: Mon, 16 Dec 2013 14:26:30 +0100 From: =?ISO-8859-1?Q?Andreas_F=E4rber?= MIME-Version: 1.0 References: <20131214002607.ffe2f4cc49f976b515ac4c0e@gmail.com> In-Reply-To: Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable Subject: Re: [Qemu-devel] a QOM Coding Conventions question List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: Peter Crosthwaite , Pantelis Koukousoulas , Antony Pavlov Cc: Peter Maydell , QEMU Developers , Anthony Liguori Hi guys, Am 16.12.2013 13:48, schrieb Peter Crosthwaite: > On Sun, Dec 15, 2013 at 7:02 PM, Pantelis Koukousoulas > wrote: >> Why not add "protected" then for the fields that are only >> meant to be accessible by the implementation but not >> public ? >> >=20 > Ok by me if the documentation generation can be cleanly and easily > taught to interpret this correctly. I don't know much about the docs > TBH. /*< private >*/ and /*< public >*/ are the only two visibility tags supported by gtk-doc [1] (private=3Doff and public=3Don, basically), so unless someone sets out to write better tools, that won't work as intende= d. And we do want to document what the meaning of certain fields is, so using private everywhere is counterproductive. The main reason why the gtk-doc patches [2] keep catching dust is that the gtk-doc scanner tool makes some assumptions about coding style that don't hold true for QEMU and thus required a slightly patched version of gtk-doc (patches posted by Anthony Liguori). So someone contributing a working gtk-doc compatible scanner (or getting upstream gtk-doc to accept the necessary changes) might actually be appreciated - in which case we could restart the discussion of mark-up extensions. Until then you can use human-readable comments to indicate that something is not supposed to be touched (which I personally consider the historical default though). That said, the intent in the QOM usage that I adopted from Anthony L. is to hide the implementation-specific parent field, just like I have been fighting to get it out of DO_UPCAST() and related usage patterns. The standardized name parent_obj serves to allow for grep'ing and together with the requested spacing after the parent_obj field serves to aid in visually spotting which structs are related to QOM. Apart from the parent field, we have encouraged to group internal data fields such as MemoryRegions vs. public child<> and link<> properties. HTH, Andreas [1] https://developer.gnome.org/gtk-doc-manual/1.18/documenting_symbols.html.= en [2] http://repo.or.cz/w/qemu/afaerber.git/shortlog/refs/heads/gtk-doc --=20 SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N=FCrnberg, Germany GF: Jeff Hawn, Jennifer Guild, Felix Imend=F6rffer; HRB 16746 AG N=FCrnbe= rg