From c7239c2f29ac9b288a48bff7458f8709ee4f7b4b Mon Sep 17 00:00:00 2001
From: Ben Pfaff <blp@nicira.com>
Date: Mon, 11 Jan 2010 13:30:15 -0800
Subject: [PATCH] ovsdb: Improve comments.

Suggested by Justin Pettit.
---
 lib/ovsdb-data.h  | 16 +++++++++++++++-
 lib/ovsdb-types.h | 19 ++++++++++++++-----
 2 files changed, 29 insertions(+), 6 deletions(-)

diff --git a/lib/ovsdb-data.h b/lib/ovsdb-data.h
index 18b8841c..6ee5f9ac 100644
--- a/lib/ovsdb-data.h
+++ b/lib/ovsdb-data.h
@@ -73,7 +73,21 @@ struct ovsdb_error *ovsdb_atom_from_json(union ovsdb_atom *,
 struct json *ovsdb_atom_to_json(const union ovsdb_atom *,
                                 enum ovsdb_atomic_type);
 
-/* One value of an OVSDB type (given by struct ovsdb_type). */
+/* An instance of an OVSDB type (given by struct ovsdb_type).
+ *
+ * 'n' is constrained by the ovsdb_type's 'n_min' and 'n_max'.
+ *
+ * If 'n' is nonzero, then 'keys' points to an array of 'n' atoms of the type
+ * specified by the ovsdb_type's 'key_type'.  (Otherwise, 'keys' should be
+ * null.)
+ *
+ * If 'n' is nonzero and the ovsdb_type's 'value_type' is not OVSDB_TYPE_VOID,
+ * then 'values' points to an array of 'n' atoms of the type specified by the
+ * 'value_type'.  (Otherwise, 'values' should be null.)
+ *
+ * Thus, for 'n' > 0, 'keys' will always be nonnull and 'values' will be
+ * nonnull only for "map" types.
+ */
 struct ovsdb_datum {
     unsigned int n;             /* Number of 'keys' and 'values'. */
     union ovsdb_atom *keys;     /* Each of the ovsdb_type's 'key_type'. */
diff --git a/lib/ovsdb-types.h b/lib/ovsdb-types.h
index 78d76c97..b9b3d5a0 100644
--- a/lib/ovsdb-types.h
+++ b/lib/ovsdb-types.h
@@ -1,4 +1,4 @@
-/* Copyright (c) 2009 Nicira Networks
+/* Copyright (c) 2009, 2010 Nicira Networks
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -42,13 +42,22 @@ struct ovsdb_error *ovsdb_atomic_type_from_json(enum ovsdb_atomic_type *,
 const char *ovsdb_atomic_type_to_string(enum ovsdb_atomic_type);
 struct json *ovsdb_atomic_type_to_json(enum ovsdb_atomic_type);
 
-/* An OVSDB type.  One of:
+/* An OVSDB type.
  *
- *      - An atomic type.
+ * Several rules constrain the valid types.  See ovsdb_type_is_valid() (in
+ * ovsdb-types.c) for details.
  *
- *      - A set of atomic types.
+ * If 'value_type' is OVSDB_TYPE_VOID, 'n_min' is 1, and 'n_max' is 1, then the
+ * type is a single atomic 'key_type'.
  *
- *      - A map from one atomic type to another.
+ * If 'value_type' is OVSDB_TYPE_VOID and 'n_min' or 'n_max' (or both) has a
+ * value other than 1, then the type is a set of 'key_type'.  If 'n_min' is 0
+ * and 'n_max' is 1, then the type can also be considered an optional
+ * 'key_type'.
+ *
+ * If 'value_type' is not OVSDB_TYPE_VOID, then the type is a map from
+ * 'key_type' to 'value_type'.  If 'n_min' is 0 and 'n_max' is 1, then the type
+ * can also be considered an optional pair of 'key_type' and 'value_type'.
  */
 struct ovsdb_type {
     enum ovsdb_atomic_type key_type;
-- 
2.30.2