[ovs-dev] [Simple DB Stats 04/11] ovsdb-idl: Start documenting the public interface.

[Ben Pfaff]

On Tue, Jun 22, 2010 at 03:17:55PM -0700, Justin Pettit wrote:
> On Jun 10, 2010, at 5:14 PM, Ben Pfaff wrote:
> 
> > +/* Creates and returns a connection to database 'remote', which should be in a
> > + * form acceptable to jsonrpc_session_open().  The connection will maintain an
> > + * in-memory replica of the remote database whose schema is described by
> > + * 'class'.  (Ordinarily 'class' is compiled from an OVSDB schema automatically
> > + * by ovsdb-idlc.) */
> > struct ovsdb_idl *
> > ovsdb_idl_create(const char *remote, const struct ovsdb_idl_class *class)
> 
> Should the "class" argument be renamed, in case any of our C++ friends
> decide to use the database?

They are just #include'ing the header files from C++.  If they were
trying to compile our .c files as C++ then we'd be getting a lot more
patches ;-)

> > +/* Processes a batch of messages from the database server on 'idl'.  Returns
> > + * true if the database as seen through 'idl' changed, true if it did not
> > + * change.  The initial fetch of the entire contents of the remote database is
> > + * considered to be one kind of change.
> 
> I assume you meant "false if it did not change".

Thanks, yes, fixed.

> > --- a/lib/ovsdb-idl.h
> > +++ b/lib/ovsdb-idl.h
> > @@ -16,6 +16,20 @@
> > #ifndef OVSDB_IDL_H
> > #define OVSDB_IDL_H 1
> > 
> > +/* Open vSwitch Database Interface Definition Language (OVSDB IDL).
> > + *
> > + * The OVSDB IDL maintains an in-memory replica of a database.  It issues RPC
> > + * requests to an OVSDB database server and parses the responses, converting
> > + * raw JSON into data structures that are easier for clients to digest.  Most
> > + * notably, references to UUIDs become C pointers.
> 
> I assume you mean the UUIDs to connect between tables.  It may be nice
> to clarify this, since UUIDs are used elsewhere in the system for a
> different purpose.

OK, thanks.  Is "...references to rows via UUID become C pointers."
clearer?  Or suggest some wording; I'm too close to the system to
document it well.