[ovs-dev] [ovsdb-idlc 2/4] ovsdb-idlc: Generate comments for "*_set" functions.

[Justin Pettit]

Signed-off-by: Justin Pettit <jpettit at nicira.com>
---
 ovsdb/ovsdb-idlc.in |   74 +++++++++++++++++++++++++++++++++++++++-----------
 1 files changed, 57 insertions(+), 17 deletions(-)

diff --git a/ovsdb/ovsdb-idlc.in b/ovsdb/ovsdb-idlc.in
index 55b695e..fa78736 100755
--- a/ovsdb/ovsdb-idlc.in
+++ b/ovsdb/ovsdb-idlc.in
@@ -28,13 +28,25 @@ def constify(cType, const):
     else:
         return cType
 
-def cMembers(prefix, columnName, column, const):
+def cMembers(prefix, tableName, columnName, column, const):
+    comment = ""
     type = column.type
 
     if type.is_smap():
-        return [{'name': columnName,
-                 'type': 'struct smap ',
-                 'comment': ''}]
+        comment = """
+/* Sets the "%(c)s" column's value from the "%(t)s" table in 'row'
+ * to '%(c)s'.
+ *
+ * The caller retains ownership of '%(c)s' and everything in it. */""" \
+             % {'c': columnName,
+                't': tableName}
+        return (comment, [{'name': columnName,
+                           'type': 'struct smap ',
+                           'comment': ''}])
+
+    comment = """
+/* Sets the "%s" column from the "%s" table in 'row' to
+""" % (columnName, tableName)
 
     if type.n_min == 1 and type.n_max == 1:
         singleton = True
@@ -47,24 +59,45 @@ def cMembers(prefix, columnName, column, const):
             pointer = '*'
 
     if type.value:
-        key = {'name': "key_%s" % columnName,
+        keyName = "key_%s" % columnName
+        valueName = "value_%s" % columnName
+
+        key = {'name': keyName,
                'type': constify(type.key.toCType(prefix) + pointer, const),
                'comment': ''}
-        value = {'name': "value_%s" % columnName,
+        value = {'name': valueName,
                  'type': constify(type.value.toCType(prefix) + pointer, const),
                  'comment': ''}
+
+        if singleton:
+            comment += " * the map with key '%s' and value '%s'\n *" % (keyName, valueName)
+        else:
+            comment += " * the map with keys '%s' and values '%s'\n *" % (keyName, valueName)
         members = [key, value]
     else:
         m = {'name': columnName,
              'type': constify(type.key.toCType(prefix) + pointer, const),
              'comment': type.cDeclComment()}
+
+        if singleton:
+            comment += " * '%s'" % columnName
+        else:
+            comment += " * the '%s' set" % columnName
         members = [m]
 
     if not singleton and not type.is_optional_pointer():
-        members.append({'name': 'n_%s' % columnName,
+        sizeName = "n_%s" % columnName
+
+        comment += " with '%s' entries" % sizeName
+        members.append({'name': sizeName,
                         'type': 'size_t ',
                         'comment': ''})
-    return members
+
+    comment += """. 
+ *
+ * The caller retains ownership of the arguments. */"""
+
+    return (comment, members)
 
 def printCIDLHeader(schemaFile):
     schema = parseSchema(schemaFile)
@@ -92,7 +125,9 @@ def printCIDLHeader(schemaFile):
         print "\tstruct ovsdb_idl_row header_;"
         for columnName, column in sorted(table.columns.iteritems()):
             print "\n\t/* %s column. */" % columnName
-            for member in cMembers(prefix, columnName, column, False):
+            comment, members = cMembers(prefix, tableName,
+                                        columnName, column, False)
+            for member in members:
                 print "\t%(type)s%(name)s;%(comment)s" % member
         print "};"
 
@@ -150,8 +185,9 @@ struct %(s)s *%(s)s_insert(struct ovsdb_idl_txn *);
             if column.type.is_smap():
                 args = ['const struct smap *']
             else:
-                args = ['%(type)s%(name)s' % member for member
-                        in cMembers(prefix, columnName, column, True)]
+                comment, members = cMembers(prefix, tableName, columnName,
+                                            column, True)
+                args = ['%(type)s%(name)s' % member for member in members]
             print '%s);' % ', '.join(args)
 
         print
@@ -475,9 +511,12 @@ const struct ovsdb_datum *
         for columnName, column in sorted(table.columns.iteritems()):
             type = column.type
 
+            comment, members = cMembers(prefix, tableName, columnName,
+                                        column, True)
+
             if type.is_smap():
-                print """
-void
+                print comment
+                print """void
 %(s)s_set_%(c)s(const struct %(s)s *row, const struct smap *%(c)s)
 {
     struct ovsdb_datum datum;
@@ -505,15 +544,13 @@ void
                         &%(s)s_columns[%(S)s_COL_%(C)s],
                         &datum);
 }
-""" % {'s': structName,
+""" % {'t': tableName,
+       's': structName,
        'S': structName.upper(),
        'c': columnName,
        'C': columnName.upper()}
                 continue
 
-
-            print '\nvoid'
-            members = cMembers(prefix, columnName, column, True)
             keyVar = members[0]['name']
             nVar = None
             valueVar = None
@@ -524,6 +561,9 @@ void
             else:
                 if len(members) > 1:
                     nVar = members[1]['name']
+
+            print comment
+            print 'void'
             print '%(s)s_set_%(c)s(const struct %(s)s *row, %(args)s)' % \
                 {'s': structName, 'c': columnName,
                  'args': ', '.join(['%(type)s%(name)s' % m for m in members])}
-- 
1.7.5.4