From 0c06bcbb76cd43877167999967748f1b60a3312d Mon Sep 17 00:00:00 2001
From: cole-barefoot <cschlesinger@barefootnetworks.com>
Date: Mon, 1 May 2017 17:25:29 -0700
Subject: [PATCH] Add Doxygen comments for the TableKeyExtraction pass. (#528)

* Add Doxygen comments for tableKeyNames pass.

* Revision based on feedback from @mbudiu-vmw.

* Move examples from method comments to class comment.
---
 frontends/p4/tableKeyNames.cpp | 17 ++++++++++++++--
 frontends/p4/tableKeyNames.h   | 36 +++++++++++++++++++++++++++-------
 2 files changed, 44 insertions(+), 9 deletions(-)

diff --git a/frontends/p4/tableKeyNames.cpp b/frontends/p4/tableKeyNames.cpp
index 9a8cd299caa..a208a0dd497 100644
--- a/frontends/p4/tableKeyNames.cpp
+++ b/frontends/p4/tableKeyNames.cpp
@@ -18,6 +18,12 @@ limitations under the License.
 
 namespace P4 {
 
+/** Generate control plane names for simple expressions that appear in table
+ * keys without `@name` annotations.
+ *
+ * Emit a compilation error if the IR contains complex expressions without
+ * `@name` annotations.
+ */
 class KeyNameGenerator : public Inspector {
     std::map<const IR::Expression*, cstring> name;
     const TypeMap* typeMap;
@@ -27,10 +33,14 @@ class KeyNameGenerator : public Inspector {
     { setName("KeyNameGenerator"); }
 
     void error(const IR::Expression* expression) {
-        ::error("%1%: Complex key expression requires a @name annotation", expression);
+        ::error(
+            "%1%: Complex key expression requires a @name annotation",
+            expression);
     }
 
-    void postorder(const IR::Expression* expression) override { error(expression); }
+    void postorder(const IR::Expression* expression) override {
+        error(expression);
+    }
 
     void postorder(const IR::PathExpression* expression) override {
         name.emplace(expression, expression->path->toString());
@@ -58,6 +68,8 @@ class KeyNameGenerator : public Inspector {
     }
 
     void postorder(const IR::BAnd *expression) override {
+        // TODO: this exists for P4_14 to P4_16 conversion and should live in
+        // the converter, not here.
         if (expression->right->is<IR::Constant>()) {
             if (cstring l = getName(expression->left))
                 name.emplace(expression, l);
@@ -72,6 +84,7 @@ class KeyNameGenerator : public Inspector {
         name.emplace(expression, expression->toString());
     }
 
+
     void postorder(const IR::Slice* expression) override {
         cstring e0 = getName(expression->e0);
         cstring e1 = getName(expression->e1);
diff --git a/frontends/p4/tableKeyNames.h b/frontends/p4/tableKeyNames.h
index 38ea6582830..639eb256eee 100644
--- a/frontends/p4/tableKeyNames.h
+++ b/frontends/p4/tableKeyNames.h
@@ -23,13 +23,35 @@ limitations under the License.
 
 namespace P4 {
 
-/**
-Adds a "@name" annotation to each table key that does not have a name.
-The string used for the name is derived from the expression itself -
-if the expression is "simple" enough.  If the expression is not
-simple the compiler will give an error.  Simple expressions are
-PathExpression, ArrayIndex, Member, .isValid(), Constant, Slice
-*/
+/** Adds a "@name" annotation to each table key that does not have a name.
+ * The string used for the name is derived from the expression itself - if
+ * the expression is "simple" enough.  If the expression is not simple the
+ * compiler will give an error.  Simple expressions are:
+ * - .isValid(),
+ * - ArrayIndex,
+ * - BAnd (where at least one operand is constant),
+ * - Constant,
+ * - Member,
+ * - PathExpression,
+ * - Slice.
+ *
+ * Examples of control plane names generated from expressions:
+ * - `arr[16w5].f` : `@name("arr[5].f")`
+ * - `f & 0x3` : `@name("f")`
+ * - `.foo` : `@name(".foo")`
+ * - `foo.bar` : `@name("foo.bar")`
+ * - `f.isValid()` : `@name("f.isValid()")`
+ * - `f[3:0]` : `@name("f[3:0]")`
+ *
+ * @pre This must run before passes that change key expressions, eg. constant
+ * folding.  Otherwise the generated control plane names may not match the
+ * syntax of the original P4 program.
+ * 
+ * @post All key fields have `@name` annotations.
+ *
+ * Emit a compilation error if the program contains complex key expressions
+ * without `@name` annotations.
+ */
 class DoTableKeyNames : public Transform {
     const TypeMap* typeMap;
  public: