Index: src/Validate/Autogen.hpp
===================================================================
--- src/Validate/Autogen.hpp	(revision af75a874034d5595d53a615e8e529fa039610605)
+++ src/Validate/Autogen.hpp	(revision 11df881444fe5fe1691782e35ebfec8a06555fa6)
@@ -22,4 +22,6 @@
 namespace Validate {
 
+/// Generate routines for all data types in the translation unit.
+/// A lot of passes have to happen either before or after this pass.
 void autogenerateRoutines( ast::TranslationUnit & translationUnit );
 
Index: src/Validate/CompoundLiteral.hpp
===================================================================
--- src/Validate/CompoundLiteral.hpp	(revision af75a874034d5595d53a615e8e529fa039610605)
+++ src/Validate/CompoundLiteral.hpp	(revision 11df881444fe5fe1691782e35ebfec8a06555fa6)
@@ -23,4 +23,5 @@
 
 /// Use variables to implement compound literals.
+/// Must happen after auto-gen routines are added.
 void handleCompoundLiterals( ast::TranslationUnit & translationUnit );
 
Index: src/Validate/EnumAndPointerDecay.cpp
===================================================================
--- src/Validate/EnumAndPointerDecay.cpp	(revision af75a874034d5595d53a615e8e529fa039610605)
+++ src/Validate/EnumAndPointerDecay.cpp	(revision 11df881444fe5fe1691782e35ebfec8a06555fa6)
@@ -5,5 +5,5 @@
 // file "LICENCE" distributed with Cforall.
 //
-// EnumAndPointerDecay.cpp --
+// EnumAndPointerDecay.cpp -- Normalizes enumerations and types in functions.
 //
 // Author           : Andrew Beach
Index: src/Validate/EnumAndPointerDecay.hpp
===================================================================
--- src/Validate/EnumAndPointerDecay.hpp	(revision af75a874034d5595d53a615e8e529fa039610605)
+++ src/Validate/EnumAndPointerDecay.hpp	(revision 11df881444fe5fe1691782e35ebfec8a06555fa6)
@@ -5,5 +5,5 @@
 // file "LICENCE" distributed with Cforall.
 //
-// EnumAndPointerDecay.hpp --
+// EnumAndPointerDecay.hpp -- Normalizes enumerations and types in functions.
 //
 // Author           : Andrew Beach
@@ -22,4 +22,7 @@
 namespace Validate {
 
+/// Fix the parameter and return types of functions. Also assigns types to
+/// enumeration values. This must happen before Link Reference to Types,
+/// it needs correct types for mangling, and before auto-gen.
 void decayEnumsAndPointers( ast::TranslationUnit & translationUnit );
 
Index: src/Validate/FindSpecialDecls.h
===================================================================
--- src/Validate/FindSpecialDecls.h	(revision af75a874034d5595d53a615e8e529fa039610605)
+++ src/Validate/FindSpecialDecls.h	(revision 11df881444fe5fe1691782e35ebfec8a06555fa6)
@@ -5,5 +5,5 @@
 // file "LICENCE" distributed with Cforall.
 //
-// FindSpecialDeclarations.h --
+// FindSpecialDeclarations.h -- Find special declarations used in the compiler.
 //
 // Author           : Rob Schluntz
@@ -43,5 +43,5 @@
 	void findSpecialDecls( std::list< Declaration * > & translationUnit );
 
-/// find and remember some of the special declarations that are useful for
+/// Find and remember some of the special declarations that are useful for
 /// generating code, so that they do not have to be discovered multiple times.
 void findGlobalDecls( ast::TranslationUnit & translationUnit );
Index: src/Validate/FixQualifiedTypes.cpp
===================================================================
--- src/Validate/FixQualifiedTypes.cpp	(revision af75a874034d5595d53a615e8e529fa039610605)
+++ src/Validate/FixQualifiedTypes.cpp	(revision 11df881444fe5fe1691782e35ebfec8a06555fa6)
@@ -5,5 +5,5 @@
 // file "LICENCE" distributed with Cforall.
 //
-// FixQualifiedTypes.cpp --
+// FixQualifiedTypes.cpp -- Replace the qualified type with a direct type.
 //
 // Author           : Andrew Beach
@@ -76,5 +76,4 @@
 							ret->qualifiers = type->qualifiers;
 							ast::TypeSubstitution sub( aggr->params, instp->params );
-							// = parent->genericSubstitution();
 							auto result = sub.apply(ret);
 							return result.node.release();
Index: src/Validate/FixQualifiedTypes.hpp
===================================================================
--- src/Validate/FixQualifiedTypes.hpp	(revision af75a874034d5595d53a615e8e529fa039610605)
+++ src/Validate/FixQualifiedTypes.hpp	(revision 11df881444fe5fe1691782e35ebfec8a06555fa6)
@@ -5,5 +5,5 @@
 // file "LICENCE" distributed with Cforall.
 //
-// FixQualifiedTypes.hpp --
+// FixQualifiedTypes.hpp -- Replace the qualified type with a direct type.
 //
 // Author           : Andrew Beach
@@ -22,4 +22,7 @@
 namespace Validate {
 
+/// Replaces qualified types with an unqualified NamedTypeDecl.
+/// Must happen after Link References To Types,
+/// because aggregate members are accessed.
 void fixQualifiedTypes( ast::TranslationUnit & translationUnit );
 
Index: src/Validate/FixReturnTypes.cpp
===================================================================
--- src/Validate/FixReturnTypes.cpp	(revision af75a874034d5595d53a615e8e529fa039610605)
+++ src/Validate/FixReturnTypes.cpp	(revision 11df881444fe5fe1691782e35ebfec8a06555fa6)
@@ -5,5 +5,5 @@
 // file "LICENCE" distributed with Cforall.
 //
-// FixReturnTypes.cpp --
+// FixReturnTypes.cpp -- Unifies the representation of return types.
 //
 // Author           : Andrew Beach
Index: src/Validate/FixReturnTypes.hpp
===================================================================
--- src/Validate/FixReturnTypes.hpp	(revision af75a874034d5595d53a615e8e529fa039610605)
+++ src/Validate/FixReturnTypes.hpp	(revision 11df881444fe5fe1691782e35ebfec8a06555fa6)
@@ -5,5 +5,5 @@
 // file "LICENCE" distributed with Cforall.
 //
-// FixReturnTypes.hpp --
+// FixReturnTypes.hpp -- Unifies the representation of return types.
 //
 // Author           : Andrew Beach
@@ -22,6 +22,7 @@
 namespace Validate {
 
-// This pass needs to happen early so that other passes can find tuple types
-// in the right places, especially for function return types.
+/// This pass needs to happen early so that other passes can find tuple types
+/// in the right places, especially for function return types.
+/// Must happen before auto-gen.
 void fixReturnTypes( ast::TranslationUnit & translationUnit );
 
Index: src/Validate/ForallPointerDecay.hpp
===================================================================
--- src/Validate/ForallPointerDecay.hpp	(revision af75a874034d5595d53a615e8e529fa039610605)
+++ src/Validate/ForallPointerDecay.hpp	(revision 11df881444fe5fe1691782e35ebfec8a06555fa6)
@@ -29,4 +29,7 @@
 /// Also checks that operator names are used properly on functions and
 /// assigns unique IDs. This is a "legacy" pass.
+/// Must be after implement concurrent keywords; because uniqueIds must be
+/// set on declaration before resolution.
+/// Must happen before auto-gen routines are added.
 void decayForallPointers( ast::TranslationUnit & transUnit );
 
Index: src/Validate/GenericParameter.cpp
===================================================================
--- src/Validate/GenericParameter.cpp	(revision af75a874034d5595d53a615e8e529fa039610605)
+++ src/Validate/GenericParameter.cpp	(revision 11df881444fe5fe1691782e35ebfec8a06555fa6)
@@ -5,5 +5,5 @@
 // file "LICENCE" distributed with Cforall.
 //
-// GenericParameter.hpp --
+// GenericParameter.hpp -- Generic parameter related passes.
 //
 // Author           : Andrew Beach
Index: src/Validate/GenericParameter.hpp
===================================================================
--- src/Validate/GenericParameter.hpp	(revision af75a874034d5595d53a615e8e529fa039610605)
+++ src/Validate/GenericParameter.hpp	(revision 11df881444fe5fe1691782e35ebfec8a06555fa6)
@@ -5,5 +5,5 @@
 // file "LICENCE" distributed with Cforall.
 //
-// GenericParameter.hpp --
+// GenericParameter.hpp -- Generic parameter related passes.
 //
 // Author           : Andrew Beach
@@ -23,4 +23,6 @@
 
 /// Perform substutions for generic parameters and fill in defaults.
+/// Check as early as possible, but it can't happen before Link References to
+/// Types and observed failing when attempted before eliminate typedef.
 void fillGenericParameters( ast::TranslationUnit & translationUnit );
 
Index: src/Validate/HoistStruct.hpp
===================================================================
--- src/Validate/HoistStruct.hpp	(revision af75a874034d5595d53a615e8e529fa039610605)
+++ src/Validate/HoistStruct.hpp	(revision 11df881444fe5fe1691782e35ebfec8a06555fa6)
@@ -22,5 +22,5 @@
 namespace Validate {
 
-/// Flattens nested type declarations.
+/// Flattens nested type declarations. (Run right after Fix Qualified Types.)
 void hoistStruct( ast::TranslationUnit & translationUnit );
 
Index: src/Validate/HoistTypeDecls.cpp
===================================================================
--- src/Validate/HoistTypeDecls.cpp	(revision af75a874034d5595d53a615e8e529fa039610605)
+++ src/Validate/HoistTypeDecls.cpp	(revision 11df881444fe5fe1691782e35ebfec8a06555fa6)
@@ -5,5 +5,5 @@
 // file "LICENCE" distributed with Cforall.
 //
-// HoistTypeDecls.cpp --
+// HoistTypeDecls.cpp -- Hoists declarations of implicitly declared types.
 //
 // Author           : Andrew Beach
Index: src/Validate/HoistTypeDecls.hpp
===================================================================
--- src/Validate/HoistTypeDecls.hpp	(revision af75a874034d5595d53a615e8e529fa039610605)
+++ src/Validate/HoistTypeDecls.hpp	(revision 11df881444fe5fe1691782e35ebfec8a06555fa6)
@@ -5,5 +5,5 @@
 // file "LICENCE" distributed with Cforall.
 //
-// HoistTypeDecls.hpp --
+// HoistTypeDecls.hpp -- Hoists declarations of implicitly declared types.
 //
 // Author           : Andrew Beach
@@ -22,4 +22,7 @@
 namespace Validate {
 
+/// There are some places where a type can be declared but are usually only
+/// referenced (with an *InstType). This inserts the declarations before
+/// they are referenced.
 void hoistTypeDecls( ast::TranslationUnit & translationUnit );
 
Index: src/Validate/LabelAddressFixer.cpp
===================================================================
--- src/Validate/LabelAddressFixer.cpp	(revision af75a874034d5595d53a615e8e529fa039610605)
+++ src/Validate/LabelAddressFixer.cpp	(revision 11df881444fe5fe1691782e35ebfec8a06555fa6)
@@ -5,5 +5,5 @@
 // file "LICENCE" distributed with Cforall.
 //
-// LabelAddressFixer.cpp --
+// LabelAddressFixer.cpp -- Create label address expressions.
 //
 // Author           : Andrew Beach
Index: src/Validate/LabelAddressFixer.hpp
===================================================================
--- src/Validate/LabelAddressFixer.hpp	(revision af75a874034d5595d53a615e8e529fa039610605)
+++ src/Validate/LabelAddressFixer.hpp	(revision 11df881444fe5fe1691782e35ebfec8a06555fa6)
@@ -5,5 +5,5 @@
 // file "LICENCE" distributed with Cforall.
 //
-// LabelAddressFixer.hpp --
+// LabelAddressFixer.hpp -- Create label address expressions.
 //
 // Author           : Andrew Beach
@@ -20,4 +20,6 @@
 namespace Validate {
 
+/// Label addresses are not actually created in the parser, this pass finds
+/// the patterns that represent the label address expression.
 void fixLabelAddresses( ast::TranslationUnit & translationUnit );
 
Index: src/Validate/LinkReferenceToTypes.hpp
===================================================================
--- src/Validate/LinkReferenceToTypes.hpp	(revision af75a874034d5595d53a615e8e529fa039610605)
+++ src/Validate/LinkReferenceToTypes.hpp	(revision 11df881444fe5fe1691782e35ebfec8a06555fa6)
@@ -22,4 +22,7 @@
 namespace Validate {
 
+/// Fills in the base value of various instance types, and some related
+/// adjustments, such as setting the sized flag.
+/// Because of the sized flag, it must happen before auto-gen.
 void linkReferenceToTypes( ast::TranslationUnit & translationUnit );
 
Index: src/Validate/ReplaceTypedef.cpp
===================================================================
--- src/Validate/ReplaceTypedef.cpp	(revision af75a874034d5595d53a615e8e529fa039610605)
+++ src/Validate/ReplaceTypedef.cpp	(revision 11df881444fe5fe1691782e35ebfec8a06555fa6)
@@ -5,5 +5,5 @@
 // file "LICENCE" distributed with Cforall.
 //
-// ReplaceTypedef.cpp --
+// ReplaceTypedef.cpp -- Fill in all typedefs with the underlying type.
 //
 // Author           : Andrew Beach
Index: src/Validate/ReplaceTypedef.hpp
===================================================================
--- src/Validate/ReplaceTypedef.hpp	(revision af75a874034d5595d53a615e8e529fa039610605)
+++ src/Validate/ReplaceTypedef.hpp	(revision 11df881444fe5fe1691782e35ebfec8a06555fa6)
@@ -5,5 +5,5 @@
 // file "LICENCE" distributed with Cforall.
 //
-// ReplaceTypedef.hpp --
+// ReplaceTypedef.hpp -- Fill in all typedefs with the underlying type.
 //
 // Author           : Andrew Beach
@@ -22,4 +22,5 @@
 namespace Validate {
 
+/// Uses of typedef are replaced with the type in the typedef.
 void replaceTypedef( ast::TranslationUnit & translationUnit );
 
Index: src/Validate/VerifyCtorDtorAssign.cpp
===================================================================
--- src/Validate/VerifyCtorDtorAssign.cpp	(revision af75a874034d5595d53a615e8e529fa039610605)
+++ src/Validate/VerifyCtorDtorAssign.cpp	(revision 11df881444fe5fe1691782e35ebfec8a06555fa6)
@@ -5,5 +5,5 @@
 // file "LICENCE" distributed with Cforall.
 //
-// VerifyCtorDtorAssign.cpp --
+// VerifyCtorDtorAssign.cpp -- Check the form of operators.
 //
 // Author           : Andrew Beach
Index: src/Validate/VerifyCtorDtorAssign.hpp
===================================================================
--- src/Validate/VerifyCtorDtorAssign.hpp	(revision af75a874034d5595d53a615e8e529fa039610605)
+++ src/Validate/VerifyCtorDtorAssign.hpp	(revision 11df881444fe5fe1691782e35ebfec8a06555fa6)
@@ -5,5 +5,5 @@
 // file "LICENCE" distributed with Cforall.
 //
-// VerifyCtorDtorAssign.hpp --
+// VerifyCtorDtorAssign.hpp -- Check the form of operators.
 //
 // Author           : Andrew Beach
@@ -22,4 +22,6 @@
 namespace Validate {
 
+/// Check that constructors, destructors and assignments all have the correct
+/// form. Must happen before auto-gen or anything that examines operators.
 void verifyCtorDtorAssign( ast::TranslationUnit & translationUnit );