Added a high-level comment to each module

src/analysis/typepal/AType.rsc

@@ -1,12 +1,14 @@
 module analysis::typepal::AType
+
+/*
+    Foundation of ATypes, to be extended for different type systems
+*/
 
 import List;
 
 extend analysis::typepal::GetLoc;
 extend analysis::typepal::TModel;
 
-// Foundation of ATypes, will be extended for different type systems
-
 data AType
     = tvar(loc tname)                                      // type variable, used for type inference
     | lazyLub(list[AType] atypes)                          // lazily computed LUB of a list of types

src/analysis/typepal/Collector.rsc

@@ -11,6 +11,10 @@ Redistribution and use in source and binary forms, with or without modification,
 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 }
 module analysis::typepal::Collector
+
+/*
+    Implementation of the ICollector interface; this is the API of TypePal's fact and constraint collector
+*/
 
 import Node;
 import Map;
@@ -133,7 +137,6 @@ void print(reqUnify(str rname, value l, value r, list[loc] dependsOn, FailMessag
     if(full) printDeps(dependsOn, indent, facts);
 }
 
-
 void print(reqError (loc src, list[loc] dependsOn, FailMessage fm), str indent, map[loc,AType] facts, bool full=true){
     println("<indent>requ for <src>");
     if(full) printDeps(dependsOn, indent, facts);

src/analysis/typepal/ConfigurableScopeGraph.rsc

@@ -1,5 +1,11 @@
 module analysis::typepal::ConfigurableScopeGraph
 
+/*
+    A ScopeGraph is the basis for TypePal's operations. It acts as a lookup function for names.
+    It is highly parameterized to reflect properties of different type systems and name binding mechanisms.
+    
+    ScopeGraphs are inspired by Kastens & Waite, Name analysis for modern languages: a general solution, SP&E, 2017
+*/
 extend analysis::typepal::Exception;
 extend analysis::typepal::ISolver;
 
@@ -132,12 +138,6 @@ data TypePalConfig(
 
         loc (str id, IdRole idRole, loc physicalLoc, str modelName, PathConfig pcfg) createLogicalLoc = defaultLogicalLoc
     );
-
-
-// ScopeGraphs inspired by Kastens & Waite, Name analysis for modern languages: a general solution, SP&E, 2017
-
-
-//data Tree;      // workaround for bug in interpreter
 
 
 // Language-specific acceptance in case of multiple outcomes of a lookup
@@ -444,8 +444,6 @@ ScopeGraph newScopeGraph(TModel tm, TypePalConfig config){
         return res;
     }
 
-
-
     public set[loc] lookupWide(Use u){
 
         // Update current paths and pathRoles

src/analysis/typepal/Exception.rsc

@@ -1,8 +1,10 @@
 module analysis::typepal::Exception
 
-extend analysis::typepal::FailMessage;
+/*
+    Exceptions that are used by TypePal
+*/
 
-// --- Exceptions
+extend analysis::typepal::FailMessage;
 
 data RuntimeException
     = TypePalUsage(str reason)                      // TypePal used incorrectly

src/analysis/typepal/FailMessage.rsc

@@ -1,5 +1,9 @@
 module analysis::typepal::FailMessage
 
+/*
+    FailMessages provide a convenient variation on Rascal's standard Message datatype. 
+    In the end, FailMessages are reduced to standard Messages.
+*/
 import Message;
 import String;
 

src/analysis/typepal/GetLoc.rsc

@@ -1,5 +1,8 @@
 module analysis::typepal::GetLoc
 
+/*
+    Convenience functions to get the location of a Tree
+*/
 import List;
 import ParseTree;
 import IO;

src/analysis/typepal/ICollector.rsc

@@ -1,8 +1,10 @@
 module analysis::typepal::ICollector
 
-extend analysis::typepal::ConfigurableScopeGraph;
+/*
+    Declaration of the ICollector interface; this is the API of TypePal's fact and constraint collector
+*/
 
-// The API of TypePal's fact and constraint collector
+extend analysis::typepal::ConfigurableScopeGraph;
 
 data Collector 
     = collector(

src/analysis/typepal/ISolver.rsc

@@ -1,11 +1,13 @@
 module analysis::typepal::ISolver
 
+/*
+    Declaration of the ISolver interface; this is the API of TypePal's constraint solver
+*/
+
 extend analysis::typepal::AType;
 extend analysis::typepal::FailMessage;
 import ParseTree;
 
-// The API of TypePal's constraint solver
-
 data Solver
     = solver(
     /* Lifecycle */     TModel () run,

src/analysis/typepal/Messenger.rsc

@@ -1,5 +1,8 @@
 module analysis::typepal::Messenger
 
+/*
+    Utilities for formatting Messages
+*/
 import ParseTree;
 import Message;
 import Exception;

src/analysis/typepal/Solver.rsc

@@ -1,5 +1,8 @@
 module analysis::typepal::Solver
 
+/*
+    Implementation of the ISolver interface; this is the API of TypePal's constraint solver
+*/
 import Set; 
 import Node;
 import Map;

src/analysis/typepal/TModel.rsc

@@ -1,5 +1,9 @@
 module analysis::typepal::TModel
 
+/*
+    A TModel (for Type Model) is the basic data structure to represent type information.
+    It can be extended to suit the needs of a specific type checker.
+*/
 import String;
 import Message;
 import List;
@@ -98,7 +102,6 @@ data TModel (
     map[str,value] store = (),
     map[loc, Define] definitions = (),
     map[loc,loc] logical2physical = (),
-    //rel[loc,loc] logical2physical = {},
     TypePalConfig config = tconfig()
 )   = tmodel();
 

src/analysis/typepal/TypePal.rsc

@@ -11,6 +11,11 @@ Redistribution and use in source and binary forms, with or without modification,
 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 }
 module analysis::typepal::TypePal
+
+/*
+    Top level module that provides all TypePal functionality to its clients
+    and also declares some convenience functions.
+*/
 
 import ParseTree;
 import Message;