ovsdb: Remove "comment" support from OVSDB schemas.

Using a separate XML file to document a schema is much more flexible.
You end up with two files (a schema and documentation for it), each of
which is readable and maintainable, instead of a single schema file that
is almost illegible.

ovsdb/OVSDB.py

@@ -21,25 +21,23 @@ def mustGetMember(json, name, expectedType, description):
     return member
 
 class DbSchema:
-    def __init__(self, name, comment, tables):
+    def __init__(self, name, tables):
         self.name = name
-        self.comment = comment
         self.tables = tables
 
     @staticmethod
     def fromJson(json):
         name = mustGetMember(json, 'name', [unicode], 'database')
-        comment = getMember(json, 'comment', [unicode], 'database')
         tablesJson = mustGetMember(json, 'tables', [dict], 'database')
         tables = {}
         for tableName, tableJson in tablesJson.iteritems():
             tables[tableName] = TableSchema.fromJson(tableJson,
                                                      "%s table" % tableName)
-        return DbSchema(name, comment, tables)
+        return DbSchema(name, tables)
 
 class IdlSchema(DbSchema):
-    def __init__(self, name, comment, tables, idlPrefix, idlHeader):
-        DbSchema.__init__(self, name, comment, tables)
+    def __init__(self, name, tables, idlPrefix, idlHeader):
+        DbSchema.__init__(self, name, tables)
         self.idlPrefix = idlPrefix
         self.idlHeader = idlHeader
 
@@ -48,39 +46,34 @@ def fromJson(json):
         schema = DbSchema.fromJson(json)
         idlPrefix = mustGetMember(json, 'idlPrefix', [unicode], 'database')
         idlHeader = mustGetMember(json, 'idlHeader', [unicode], 'database')
-        return IdlSchema(schema.name, schema.comment, schema.tables,
-                         idlPrefix, idlHeader)
+        return IdlSchema(schema.name, schema.tables, idlPrefix, idlHeader)
 
 class TableSchema:
-    def __init__(self, comment, columns):
-        self.comment = comment
+    def __init__(self, columns):
         self.columns = columns
 
     @staticmethod
     def fromJson(json, description):
-        comment = getMember(json, 'comment', [unicode], description)
         columnsJson = mustGetMember(json, 'columns', [dict], description)
         columns = {}
         for name, json in columnsJson.iteritems():
             columns[name] = ColumnSchema.fromJson(
                 json, "column %s in %s" % (name, description))
-        return TableSchema(comment, columns)
+        return TableSchema(columns)
 
 class ColumnSchema:
-    def __init__(self, comment, type, persistent):
-        self.comment = comment
+    def __init__(self, type, persistent):
         self.type = type
         self.persistent = persistent
 
     @staticmethod
     def fromJson(json, description):
-        comment = getMember(json, 'comment', [unicode], description)
         type = Type.fromJson(mustGetMember(json, 'type', [dict, unicode],
                                            description),
                              'type of %s' % description)
         ephemeral = getMember(json, 'ephemeral', [bool], description)
         persistent = ephemeral != True
-        return ColumnSchema(comment, type, persistent)
+        return ColumnSchema(type, persistent)
 
 def escapeCString(src):
     dst = ""

ovsdb/SPECS

@@ -89,25 +89,21 @@ is represented by <database-schema>, as described below.
     A JSON object with the following members:
 
         "name": <id>                            required
-        "comment": <string>                     optional
         "tables": {<id>: <table-schema>, ...}   required
 
     The "name" identifies the database as a whole.  It must be
     provided to most JSON-RPC requests to identify the database being
-    operated on.  The "comment" optionally provides more information
-    about the database.  The value of "tables" is a JSON object whose
-    names are table names and whose values are <table-schema>s.
+    operated on.  The value of "tables" is a JSON object whose names
+    are table names and whose values are <table-schema>s.
 
 <table-schema>
 
     A JSON object with the following members:
 
-        "comment": <string>                       optional
         "columns": {<id>: <column-schema>, ...}   required
 
-    The "comment" optionally provides information about this table for
-    a human reader.  The value of "columns" is a JSON object whose
-    names are column names and whose values are <column-schema>s.
+    The value of "columns" is a JSON object whose names are column
+    names and whose values are <column-schema>s.
 
     Every table has the following columns whose definitions are not
     included in the schema:
@@ -130,15 +126,13 @@ is represented by <database-schema>, as described below.
 
     A JSON object with the following members:
 
-        "comment": <string>                       optional
         "type": <type>                            required
         "ephemeral": <boolean>                    optional
 
-    The "comment" optionally provides information about this column
-    for a human reader.  The "type" specifies the type of data stored
-    in this column.  If "ephemeral" is specified as true, then this
-    column's values are not guaranteed to be durable; they may be lost
-    when the database restarts.
+    The "type" specifies the type of data stored in this column.  If
+    "ephemeral" is specified as true, then this column's values are
+    not guaranteed to be durable; they may be lost when the database
+    restarts.
 
 <type>
 

ovsdb/column.c

@@ -27,7 +27,7 @@
 #include "util.h"
 
 struct ovsdb_column *
-ovsdb_column_create(const char *name, const char *comment,
+ovsdb_column_create(const char *name,
                     bool mutable, bool persistent,
                     const struct ovsdb_type *type)
 {
@@ -36,7 +36,6 @@ ovsdb_column_create(const char *name, const char *comment,
 
     column = xzalloc(sizeof *column);
     column->name = xstrdup(name);
-    column->comment = comment ? xstrdup(comment) : NULL;
     column->mutable = mutable;
     column->persistent = persistent;
     ovsdb_type_clone(&column->type, type);
@@ -48,7 +47,7 @@ struct ovsdb_column *
 ovsdb_column_clone(const struct ovsdb_column *old)
 {
     /* Doesn't copy the column's 'index': the caller must do that. */
-    return ovsdb_column_create(old->name, old->comment,
+    return ovsdb_column_create(old->name,
                                old->mutable, old->persistent,
                                &old->type);
 }
@@ -58,15 +57,14 @@ ovsdb_column_destroy(struct ovsdb_column *column)
 {
     ovsdb_type_destroy(&column->type);
     free(column->name);
-    free(column->comment);
     free(column);
 }
 
 struct ovsdb_error *
 ovsdb_column_from_json(const struct json *json, const char *name,
                        struct ovsdb_column **columnp)
 {
-    const struct json *comment, *mutable, *ephemeral, *type_json;
+    const struct json *mutable, *ephemeral, *type_json;
     struct ovsdb_error *error;
     struct ovsdb_type type;
     struct ovsdb_parser parser;
@@ -75,7 +73,6 @@ ovsdb_column_from_json(const struct json *json, const char *name,
     *columnp = NULL;
 
     ovsdb_parser_init(&parser, json, "schema for column %s", name);
-    comment = ovsdb_parser_member(&parser, "comment", OP_STRING | OP_OPTIONAL);
     mutable = ovsdb_parser_member(&parser, "mutable",
                                 OP_TRUE | OP_FALSE | OP_OPTIONAL);
     ephemeral = ovsdb_parser_member(&parser, "ephemeral",
@@ -93,7 +90,6 @@ ovsdb_column_from_json(const struct json *json, const char *name,
 
     persistent = ephemeral ? !json_boolean(ephemeral) : true;
     *columnp = ovsdb_column_create(name,
-                                   comment ? json_string(comment) : NULL,
                                    mutable ? json_boolean(mutable) : true,
                                    persistent, &type);
 
@@ -106,9 +102,6 @@ struct json *
 ovsdb_column_to_json(const struct ovsdb_column *column)
 {
     struct json *json = json_object_create();
-    if (column->comment) {
-        json_object_put_string(json, "comment", column->comment);
-    }
     if (!column->mutable) {
         json_object_put(json, "mutable", json_boolean_create(false));
     }

ovsdb/column.h

@@ -27,7 +27,6 @@ struct ovsdb_column {
     unsigned int index;
     char *name;
 
-    char *comment;
     bool mutable;
     bool persistent;
     struct ovsdb_type type;
@@ -45,7 +44,7 @@ enum {
 };
 
 struct ovsdb_column *ovsdb_column_create(
-    const char *name, const char *comment, bool mutable, bool persistent,
+    const char *name, bool mutable, bool persistent,
     const struct ovsdb_type *);
 struct ovsdb_column *ovsdb_column_clone(const struct ovsdb_column *);
 void ovsdb_column_destroy(struct ovsdb_column *);

ovsdb/ovsdb-client.1.in

@@ -61,12 +61,12 @@ prints it in JSON format.
 .
 .IP "\fBlist-tables\fI server database\fR"
 Connects to \fIserver\fR, retrieves the schema for \fIdatabase\fR, and
-prints a table listing the names and comments (if any) on each table
+prints a table listing the name of each table
 within the database.
 .
 .IP "\fBlist-columns\fI server database \fR[\fItable\fR]"
 Connects to \fIserver\fR, retrieves the schema for \fIdatabase\fR, and
-prints a table listing the names, type, and comment (if any) on each
+prints a table listing the name and type of each
 column.  If \fItable\fR is specified, only columns in that table are
 listed; otherwise, the tables include columns in all tables.
 .

ovsdb/ovsdb-client.c

@@ -695,15 +695,11 @@ do_list_tables(int argc OVS_UNUSED, char *argv[])
     schema = fetch_schema(argv[1], argv[2]);
     table_init(&t);
     table_add_column(&t, "Table");
-    table_add_column(&t, "Comment");
     SHASH_FOR_EACH (node, &schema->tables) {
         struct ovsdb_table_schema *ts = node->data;
 
         table_add_row(&t);
         table_add_cell(&t, ts->name);
-        if (ts->comment) {
-            table_add_cell(&t, ts->comment);
-        }
     }
     ovsdb_schema_destroy(schema);
     table_print(&t);
@@ -724,7 +720,6 @@ do_list_columns(int argc OVS_UNUSED, char *argv[])
     }
     table_add_column(&t, "Column");
     table_add_column(&t, "Type");
-    table_add_column(&t, "Comment");
     SHASH_FOR_EACH (table_node, &schema->tables) {
         struct ovsdb_table_schema *ts = table_node->data;
 
@@ -741,9 +736,6 @@ do_list_columns(int argc OVS_UNUSED, char *argv[])
                 }
                 table_add_cell(&t, column->name);
                 table_add_cell_nocopy(&t, json_to_string(type, JSSF_SORT));
-                if (column->comment) {
-                    table_add_cell(&t, column->comment);
-                }
 
                 json_destroy(type);
             }

ovsdb/ovsdb-idlc.in

@@ -231,10 +231,7 @@ static struct %(s)s *
     for tableName, table in sorted(schema.tables.iteritems()):
         structName = "%s%s" % (prefix, tableName.lower())
         print ""
-        if table.comment != None:
-            print "/* %s table (%s). */" % (tableName, table.comment)
-        else:
-            print "/* %s table. */" % (tableName)
+        print "/* %s table. */" % (tableName)
 
         # Parse functions.
         for columnName, column in sorted(table.columns.iteritems()):

ovsdb/ovsdb.c

@@ -26,13 +26,12 @@
 #include "transaction.h"
 
 struct ovsdb_schema *
-ovsdb_schema_create(const char *name, const char *comment)
+ovsdb_schema_create(const char *name)
 {
     struct ovsdb_schema *schema;
 
     schema = xzalloc(sizeof *schema);
     schema->name = xstrdup(name);
-    schema->comment = comment ? xstrdup(comment) : NULL;
     shash_init(&schema->tables);
 
     return schema;
@@ -44,7 +43,7 @@ ovsdb_schema_clone(const struct ovsdb_schema *old)
     struct ovsdb_schema *new;
     struct shash_node *node;
 
-    new = ovsdb_schema_create(old->name, old->comment);
+    new = ovsdb_schema_create(old->name);
     SHASH_FOR_EACH (node, &old->tables) {
         const struct ovsdb_table_schema *ts = node->data;
 
@@ -63,7 +62,6 @@ ovsdb_schema_destroy(struct ovsdb_schema *schema)
         ovsdb_table_schema_destroy(node->data);
     }
     shash_destroy(&schema->tables);
-    free(schema->comment);
     free(schema->name);
     free(schema);
 }
@@ -118,7 +116,7 @@ struct ovsdb_error *
 ovsdb_schema_from_json(struct json *json, struct ovsdb_schema **schemap)
 {
     struct ovsdb_schema *schema;
-    const struct json *name, *comment, *tables;
+    const struct json *name, *tables;
     struct ovsdb_error *error;
     struct shash_node *node;
     struct ovsdb_parser parser;
@@ -127,15 +125,13 @@ ovsdb_schema_from_json(struct json *json, struct ovsdb_schema **schemap)
 
     ovsdb_parser_init(&parser, json, "database schema");
     name = ovsdb_parser_member(&parser, "name", OP_ID);
-    comment = ovsdb_parser_member(&parser, "comment", OP_STRING | OP_OPTIONAL);
     tables = ovsdb_parser_member(&parser, "tables", OP_OBJECT);
     error = ovsdb_parser_finish(&parser);
     if (error) {
         return error;
     }
 
-    schema = ovsdb_schema_create(json_string(name),
-                                 comment ? json_string(comment) : NULL);
+    schema = ovsdb_schema_create(json_string(name));
     SHASH_FOR_EACH (node, json_object(tables)) {
         struct ovsdb_table_schema *table;
 
@@ -190,9 +186,6 @@ ovsdb_schema_to_json(const struct ovsdb_schema *schema)
 
     json = json_object_create();
     json_object_put_string(json, "name", schema->name);
-    if (schema->comment) {
-        json_object_put_string(json, "comment", schema->comment);
-    }
 
     tables = json_object_create();
 

ovsdb/ovsdb.h

@@ -29,12 +29,10 @@ struct uuid;
 /* Database schema. */
 struct ovsdb_schema {
     char *name;
-    char *comment;
     struct shash tables;        /* Contains "struct ovsdb_table_schema *"s. */
 };
 
-struct ovsdb_schema *ovsdb_schema_create(const char *name,
-                                         const char *comment);
+struct ovsdb_schema *ovsdb_schema_create(const char *name);
 struct ovsdb_schema *ovsdb_schema_clone(const struct ovsdb_schema *);
 void ovsdb_schema_destroy(struct ovsdb_schema *);