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

[Antony Pavlov <antonynpavlov@gmail.com>]

On Sun, 15 Dec 2013 09:06:30 +1000
Peter Crosthwaite <peter.crosthwaite@xilinx.com> wrote:

> On Sat, Dec 14, 2013 at 6:26 AM, Antony Pavlov <antonynpavlov@gmail.com> wrote:
> > Hi, Andreas!
> >
> > Here is a quote from http://wiki.qemu.org/QOMConventions
> >
> >>     a FooClass structure definition containing at least the parent class field:
> >>
> >>     typedef struct {
> >>         /*< private >*/
> >>         MyParentClass parent_class;
> >>         /*< public >*/
> >>
> >>         [any fields you need]
> >>     } FooClass;
> >
> > What do the "< private >" and "< public >" comments exactly mean here?
> 
> Private means inaccessible to everybody, including the implementation
> of class being instantiated. No one should ever dereference a private
> variable, they should be managed by QOM indirectly via casts if
> needed. Public means that at least someone can access it. Note that
> public does not declare a free-for-all. QOM class variables may be
> "public" in the sense that the class implementation may access them.
> Container devices however still can not, and they are private from
> that point of view.
> 
> For example, a timer peripheral may have a "public" ptimer, in the
> sense that the timer class derefences and modifies the timer for its
> implmentation. An embedding SoC device however can NOT use this
> despite being public, its private to the timer implementation. So in
> short:
> 
> < /* private */ > - owned by the QOM framwork - do no dereference ever
> from anywhere.
> < /* public */> - owned by the class implementation - do not
> dereference from containers.
> 
> There is also automated documentation generation using this.
> 

It's a exhaustive comment! Thanks! 
Can we add a comment like this to http://wiki.qemu.org/QOMConventions?

IMHO this public/private QOM convention is a bit confusing. I can remember
about "public/private/protected" in C++/Java. Here is a quote
from http://en.wikipedia.org/?title=C%2B%2B
 
  A public member of the class is accessible to any function.
  A private member is accessible only to functions that are
  members of that class and to functions and classes explicitly
  granted access permission by the class ("friends").

So if you use FooClass' point of view (C++/Java habit) then
 "private" and "protect" confuse you.

Can we use more detailed comments? E.g.

     typedef struct {
         /*< QOM service fields >*/
         MyParentClass parent_class;
         /*< class private fields >*/

         [any fields you need]
     } FooClass;

-- 
Best regards,
  Antony Pavlov