diff --git a/backends/p4test/midend.cpp b/backends/p4test/midend.cpp
index a99903f038..99fc611c5c 100644
--- a/backends/p4test/midend.cpp
+++ b/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
diff --git a/docs/README.md b/docs/README.md
index 71effb5ccd..af6af9da8d 100644
--- a/docs/README.md
+++ b/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`
-
diff --git a/frontends/p4/tableKeyNames.h b/frontends/p4/tableKeyNames.h
index 8d0b9ae839..38ea658283 100644
--- a/frontends/p4/tableKeyNames.h
+++ b/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:
diff --git a/frontends/p4/validateParsedProgram.h b/frontends/p4/validateParsedProgram.h
index f31c5c8bcf..0ad42e79a7 100644
--- a/frontends/p4/validateParsedProgram.h
+++ b/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 {
diff --git a/midend/tableHit.h b/midend/tableHit.h
index c5445986b3..d210ded77c 100644
--- a/midend/tableHit.h
+++ b/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;