Re: [Qemu-devel] a QOM Coding Conventions question

[Andreas Färber]

Hi guys,

Am 16.12.2013 13:48, schrieb Peter Crosthwaite:
> On Sun, Dec 15, 2013 at 7:02 PM, Pantelis  Koukousoulas
> <address@hidden> wrote:
>> Why not add "protected" then for the fields that are only
>> meant to be accessible by the implementation but not
>> public ?
>>
> 
> 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=off and public=on, basically), so
unless someone sets out to write better tools, that won't work as intended.
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

-- 
SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
GF: Jeff Hawn, Jennifer Guild, Felix Imendörffer; HRB 16746 AG Nürnberg