Hi guys, Am 16.12.2013 13:48, schrieb Peter Crosthwaite: > On Sun, Dec 15, 2013 at 7:02 PM, Pantelis Koukousoulas > <pkt...@gmail.com> 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
