Documentation improvements (#499)

* Converted some comments to Doxygen

backends/p4test/midend.cpp

@@ -73,7 +73,6 @@ MidEnd::MidEnd(CompilerOptions& options) {
     auto v1controls = new std::set<cstring>();
 
     // TODO: parser loop unrolling
-    // TODO: improve copy propagation
     // TODO: simplify actions which are too complex
     // TODO: lower errors to integers
     // TODO: handle bit-slices as out arguments

docs/README.md

@@ -23,7 +23,7 @@ p4c
 │   └── p4                    -- P4_16 front-end
 ├── ir                        -- core internal representation
 ├── lib                       -- common utilities (libp4toolkit.a)
-├── m4                        -- gnu m4 macro
+├── m4                        -- m4 macros used by autotools
 ├── midend                    -- code that may be useful for writing mid-ends
 ├── p4include                 -- standard P4 files needed by the compiler (e.g., core.p4)
 ├── test                      -- test code
@@ -258,7 +258,7 @@ output:
 ## Compiler Driver
 
 **p4c** is a compiler driver. The goal is to provide a consistent user interface
-across different p4 backends and work flows. The compiler driver is written in 
+across different p4 backends and work flows. The compiler driver is written in
 Python. It can be extended for custom backends.
 
 The usage of the driver is as follows:
@@ -300,11 +300,11 @@ makefile variable.
 p4c_PYTHON += p4c.custom.cfg
 ```
 
-There is an global variable `config` in p4c compiler driver that stores the build steps 
+There is an global variable `config` in p4c compiler driver that stores the build steps
 for a particular target. By default, the bmv2 and ebpf backends are supported. Each backend
-is identified with a triplet: **target-arch-vendor**. For example, the default bmv2 backend is 
+is identified with a triplet: **target-arch-vendor**. For example, the default bmv2 backend is
 identified as `bmv2-*-p4org`. The * is a wildcard to represent any architecture. User may choose
-to specify the architecture string to use different compilation flow for different backend 
+to specify the architecture string to use different compilation flow for different backend
 architecture.
 
 A sample configuration file looks as follows:
@@ -321,6 +321,5 @@ config.target.append("bmv2-psa-p4org")
 
 After adding the new configuration file, rerun `bootstrap.sh`
 
-For testing purpose, p4c will be installed in the build/ directory when executing `make`. 
+For testing purpose, p4c will be installed in the build/ directory when executing `make`.
 User can install `p4c` to other system path by running `make install`
-

frontends/p4/tableKeyNames.h

@@ -23,11 +23,13 @@ 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
+PathExpression, ArrayIndex, Member, .isValid(), Constant, Slice
+*/
 class DoTableKeyNames : public Transform {
     const TypeMap* typeMap;
  public:

frontends/p4/validateParsedProgram.h

@@ -41,6 +41,7 @@ namespace P4 {
    - switch statements do not occur in actions
    - instantiations do not occur in actions
    - constructors are not invoked in actions
+   - returns and exits do not appear in parsers
    - extern constructors have the same name as the enclosing extern
  */
 class ValidateParsedProgram final : public Inspector {

midend/tableHit.h

@@ -22,14 +22,16 @@ limitations under the License.
 
 namespace P4 {
 
-// Convert
-// tmp = t.apply().hit
-//    into
-// if (t.apply().hit)
-//    tmp = true;
-// else
-//    tmp = false;
-// This may be needed by some back-ends which only support hit test in conditionals
+/**
+Convert
+tmp = t.apply().hit
+   into
+if (t.apply().hit)
+   tmp = true;
+else
+   tmp = false;
+This may be needed by some back-ends which only support hit test in conditionals
+*/
 class DoTableHit : public Transform {
     ReferenceMap* refMap;
     TypeMap* typeMap;