Responding to Brian's excellent pull request comments.

Author: psteinfeld

documentation/ImplementingASemanticCheck.md

@@ -1,4 +1,4 @@
-<!--===- documentation/FrontEndTutorial.md 
+<!--===- documentation/ImplementingASemanticCheck.md 
   
    Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
    See https://llvm.org/LICENSE.txt for license information.
@@ -61,7 +61,7 @@ of the call to `intentOutFunc()`:
 
 I also used this program to produce a parse tree for the program using the command:
 ```bash
-  ./bin/f18 -fdebug-dump-parse-tree -fparse-only testfun.f90
+  f18 -fdebug-dump-parse-tree -fparse-only testfun.f90
 ```
 
 Here's the relevant fragment of the parse tree produced by the compiler:
@@ -111,9 +111,9 @@ checking had already taken place.
 Most semantic checks for statements are implemented by walking the parse tree
 and performing analysis on the nodes they visit.  My plan was to use this
 method.  The infrastructure for walking the parse tree for statement semantic
-checking is implemented in the files .../lib/semantics/semantics.[cc,h].
+checking is implemented in the files `lib/semantics/semantics.cpp`.
 Here's a fragment of the declaration of the framework's parse tree visitor from
-.../lib/semantics/semantics.cc:
+`lib/semantics/semantics.cpp`:
 
 ```C++
   // A parse tree visitor that calls Enter/Leave functions from each checker
@@ -136,7 +136,7 @@ Here's a fragment of the declaration of the framework's parse tree visitor from
 Since FUNCTION calls are a kind of expression, I was planning to base my
 implementation on the contents of `parser::Expr` nodes.  I would need to define
 either an `Enter()` or `Leave()` function whose parameter was a `parser::Expr`
-node.  Here's the declaration I put into check-do.h:
+node.  Here's the declaration I put into `lib/semantics/check-do.h`:
 
 ```C++
   void Leave(const parser::Expr &);
@@ -148,12 +148,12 @@ arbitrarily chose to implement the `Leave()` function to visit the parse tree
 node.
 
 Since my semantic check was focused on DO CONCURRENT statements, I added it to
-the file .../lib/semantics/check-do.cc where most of the semantic checking for
+the file `lib/semantics/check-do.cpp` where most of the semantic checking for
 DO statements already lived.
 
 ## Taking advantage of prior work
 When implementing a similar check for SUBROUTINE calls, I created a utility
-functions in .../lib/semantics/semantics.[cc.h] to emit messages if
+functions in `lib/semantics/semantics.cpp` to emit messages if
 a symbol corresponding to an active DO variable was being potentially modified:
 
 ```C++
@@ -175,21 +175,22 @@ functions.  The second is needed to determine whether to call them.
 
 ## Finding the source location
 The source code location information that I'd need for the error message must
-come from the parse tree.  I looked in the file .../lib/parser/parse-tree.h and
-determined that a `struct Expr` contained source location information since
-it had the field `CharBlock source`.  Thus, if I visited a
-`parser::Expr` node, I could get the source location information for the
-associated expression.
+come from the parse tree.  I looked in the file
+`include/flang/parser/parse-tree.h` and determined that a `struct Expr`
+contained source location information since it had the field `CharBlock
+source`.  Thus, if I visited a `parser::Expr` node, I could get the source
+location information for the associated expression.
 
 ## Determining the `INTENT`
 I knew that I could find the `INTENT` of the dummy argument associated with the
 actual argument from the function called `dummyIntent()` in the class
-`evaluate::ActualArgument` in the file .../lib/evaluate/call.h.  So if I could
-find an `evaluate::ActualArgument` in an expression, I could determine the
-`INTENT` of the associated dummy argument.  I knew that it was valid to call
-`dummyIntent()` because the data on which `dummyIntent()`  depends is
-established during semantic processing for expressions, and the semantic
-processing for expressions happens before semantic checking for DO constructs.
+`evaluate::ActualArgument` in the file `include/flang/evaluate/call.h`.  So
+if I could find an `evaluate::ActualArgument` in an expression, I could
+  determine the `INTENT` of the associated dummy argument.  I knew that it was
+  valid to call `dummyIntent()` because the data on which `dummyIntent()`
+  depends is established during semantic processing for expressions, and the
+  semantic processing for expressions happens before semantic checking for DO
+  constructs.
 
 In my prior work on checking the INTENT of arguments for SUBROUTINE calls,
 the parse tree held a node for the call (a `parser::CallStmt`) that contained
@@ -210,11 +211,11 @@ For a FUNCTION call, though, there is no similar way to get from a parse tree
 node to an `evaluate::ProcedureRef` node.  But I knew that there was an
 existing framework used in DO construct semantic checking that traversed an
 `evaluate::Expr` node collecting `semantics::Symbol` nodes.  I guessed that I'd
-be able to use a similar framework to traverse an ` evaluate::Expr`  node to
+be able to use a similar framework to traverse an `evaluate::Expr`  node to
 find all of the `evaluate::ActualArgument` nodes.  
 
-All of the declarations associated with both FUNCTION and SUBROUTINE
-calls are in .../lib/evaluate/call.h.  An `evaluate::FunctionRef` inherits from
+All of the declarations associated with both FUNCTION and SUBROUTINE calls are
+in `include/flang/evaluate/call.h`.  An `evaluate::FunctionRef` inherits from
 an `evaluate::ProcedureRef` which contains the list of
 `evaluate::ActualArgument` nodes.  But the relationship between an
 `evaluate::FunctionRef` node and its associated arguments is not relevant.  I
@@ -252,16 +253,16 @@ argument was an active DO variable.
 ## Adding a parse tree visitor
 I started my implementation by adding a visitor for `parser::Expr` nodes.
 Since this analysis is part of DO construct checking, I did this in
-.../lib/semantics/check-do.[cc,h].  I added a print statement to the visitor to
+`lib/semantics/check-do.cpp`.  I added a print statement to the visitor to
 verify that my new code was actually getting executed.  
 
-In check-do.h, I added the declaration for the visitor:
+In `lib/semantics/check-do.h`, I added the declaration for the visitor:
 
 ```C++
   void Leave(const parser::Expr &);
 ```
 
-In check-do.cc, I added an (almost empty) implementation:
+In `lib/semantics/check-do.cpp`, I added an (almost empty) implementation:
 
 ```C++
   void DoChecker::Leave(const parser::Expr &) {
@@ -272,7 +273,7 @@ In check-do.cc, I added an (almost empty) implementation:
 I then built the compiler with these changes and ran it on my test program.
 This time, I made sure to invoke semantic checking.  Here's the command I used:
 ```bash
-  ./bin/f18 -fdebug-resolve-names -fdebug-dump-parse-tree -funparse-with-symbols testfun.f90
+  f18 -fdebug-resolve-names -fdebug-dump-parse-tree -funparse-with-symbols testfun.f90
 ```
 
 This produced the output:
@@ -299,7 +300,7 @@ framework to walk the `evaluate::Expr` to gather all of the
 `evaluate::ActualArgument` nodes.  The code that I planned to model it on
 was the existing infrastructure that collected all of the `semantics::Symbol` nodes from an
 `evaluate::Expr`.  I found this implementation in
-.../lib/evaluate/tools.cc:
+`lib/evaluate/tools.cpp`:
 
 ```C++
   struct CollectSymbolsHelper
@@ -316,7 +317,8 @@ was the existing infrastructure that collected all of the `semantics::Symbol` no
   }
 ```
 
-Note that the `CollectSymbols()` function returns a `semantics::Symbolset`, which is declared in .../lib/semantics/symbol.h:
+Note that the `CollectSymbols()` function returns a `semantics::Symbolset`,
+which is declared in `include/flang/semantics/symbol.h`:
 
 ```C++
   using SymbolSet = std::set<SymbolRef>;
@@ -338,10 +340,11 @@ full `semantics::Symbol` objects into the set.  Ideally, we would be able to cre
 `std::set<Symbol &>` (a set of C++ references to symbols).  But C++ doesn't
 support sets that contain references.  This limitation is part of the rationale
 for the f18 implementation of type `common::Reference`, which is defined in
-  .../lib/common/reference.h.
+  `include/flang/common/reference.h`.
 
 `SymbolRef`, the specialization of the template `common::Reference` for
-`semantics::Symbol`, is declared in the file .../lib/semantics/symbol.h:
+`semantics::Symbol`, is declared in the file
+`include/flang/semantics/symbol.h`:
 
 ```C++
   using SymbolRef = common::Reference<const Symbol>;
@@ -351,7 +354,7 @@ So to implement something that would collect `evaluate::ActualArgument`
 nodes from an `evaluate::Expr`, I first defined the required types
 `ActualArgumentRef` and `ActualArgumentSet`.  Since these are being
 used exclusively for DO construct semantic checking (currently), I put their
-definitions into .../lib/semantics/check-do.cc:
+definitions into `lib/semantics/check-do.cpp`:
 
 
 ```C++
@@ -367,7 +370,7 @@ Since `ActualArgument` is in the namespace `evaluate`, I put the
 definition for `ActualArgumentRef` in that namespace, too.
 
 I then modeled the code to create an `ActualArgumentSet` after the code to
-collect a `SymbolSet` and put it into check-do.cc:
+collect a `SymbolSet` and put it into `lib/semantics/check-do.cpp`:
 
 
 ```C++
@@ -506,8 +509,8 @@ symbol table node (`semantics::Symbol`) for the variable.  My starting point was
 `evaluate::ActualArgument` node.  
 
 I was unsure of how to do this, so I browsed through existing code to look for
-how it treated `evaluate::ActualArgument` objects.  Since most of the code that deals with the `evaluate` namespace is in the .../lib/evaluate directory, I looked there.  I ran `grep` on all of the `.cc` files looking for
-uses of `ActualArgument`.  One of the first hits I got was in .../lib/evaluate/call.cc in the definition of `ActualArgument::GetType()`:
+how it treated `evaluate::ActualArgument` objects.  Since most of the code that deals with the `evaluate` namespace is in the lib/evaluate directory, I looked there.  I ran `grep` on all of the `.cpp` files looking for
+uses of `ActualArgument`.  One of the first hits I got was in `lib/evaluate/call.cpp` in the definition of `ActualArgument::GetType()`:
 
 ```C++
 std::optional<DynamicType> ActualArgument::GetType() const {
@@ -525,9 +528,9 @@ I noted the call to `UnwrapExpr()` that yielded a value of
 `Expr<SomeType>`.  So I guessed that I could use this member function to
 get an `evaluate::Expr<SomeType>` on which I could perform further analysis.
 
-I also knew that the header file .../lib/evaluate/tools.h held many utility
-functions for dealing with `evaluate::Expr` objects.  I was hoping to find
-something that would determine if an `evaluate::Expr` was a variable.  So
+I also knew that the header file `include/flang/evaluate/tools.h` held many
+utility functions for dealing with `evaluate::Expr` objects.  I was hoping to
+find something that would determine if an `evaluate::Expr` was a variable.  So
 I searched for `IsVariable` and got a hit immediately.  
 ```C++
   template<typename A> bool IsVariable(const A &x) {
@@ -541,7 +544,7 @@ I searched for `IsVariable` and got a hit immediately.
 
 But I actually needed more than just the knowledge that an `evaluate::Expr` was
 a variable.  I needed the `semantics::Symbol` associated with the variable.  So
-I searched in .../lib/evaluate/tools.h for functions that returned a
+I searched in `include/flang/evaluate/tools.h` for functions that returned a
 `semantics::Symbol`.  I found the following:
 
 ```C++