From f74cff622dd0eb8d4e64c014731e00fb9ea1d078 Mon Sep 17 00:00:00 2001
From: Alex Beregszaszi <alex@rtfs.hu>
Date: Tue, 19 Jun 2018 19:30:38 +0200
Subject: [PATCH] Properly explain all the analsys steps in CompilerStack

---
 libsolidity/codegen/ContractCompiler.cpp |  4 ++++
 libsolidity/interface/CompilerStack.cpp  | 14 +++++++++++++-
 libsolidity/interface/CompilerStack.h    |  3 ++-
 3 files changed, 19 insertions(+), 2 deletions(-)

diff --git a/libsolidity/codegen/ContractCompiler.cpp b/libsolidity/codegen/ContractCompiler.cpp
index bbb3db3d3..2f15a33d3 100644
--- a/libsolidity/codegen/ContractCompiler.cpp
+++ b/libsolidity/codegen/ContractCompiler.cpp
@@ -71,7 +71,11 @@ void ContractCompiler::compileContract(
 		appendDelegatecallCheck();
 
 	initializeContext(_contract, _contracts);
+	// This generates the dispatch function for externally visible functions
+	// and adds the function to the compilation queue. Additionally internal functions,
+	// which are referenced directly or indirectly will be added.
 	appendFunctionSelector(_contract);
+	// This processes the above populated queue until it is empty.
 	appendMissingFunctions();
 }
 
diff --git a/libsolidity/interface/CompilerStack.cpp b/libsolidity/interface/CompilerStack.cpp
index aa33bad80..32cb488f1 100644
--- a/libsolidity/interface/CompilerStack.cpp
+++ b/libsolidity/interface/CompilerStack.cpp
@@ -191,6 +191,8 @@ bool CompilerStack::analyze()
 			if (!resolver.performImports(*source->ast, sourceUnitsByName))
 				return false;
 
+		// This is the main name and type resolution loop. Needs to be run for every contract, because
+		// the special variables "this" and "super" must be set appropriately.
 		for (Source const* source: m_sourceOrder)
 			for (ASTPointer<ASTNode> const& node: source->ast->nodes())
 				if (ContractDefinition* contract = dynamic_cast<ContractDefinition*>(node.get()))
@@ -204,11 +206,15 @@ bool CompilerStack::analyze()
 					// thus contracts can only conflict if declared in the same source file.  This
 					// already causes a double-declaration error elsewhere, so we do not report
 					// an error here and instead silently drop any additional contracts we find.
-
 					if (m_contracts.find(contract->fullyQualifiedName()) == m_contracts.end())
 						m_contracts[contract->fullyQualifiedName()].contract = contract;
 				}
 
+		// This cannot be done in the above loop, because cross-contract types couldn't be resolved.
+		// A good example is `LibraryName.TypeName x;`.
+		//
+		// Note: this does not resolve overloaded functions. In order to do that, types of arguments are needed,
+		// which is only done one step later.
 		TypeChecker typeChecker(m_evmVersion, m_errorReporter);
 		for (Source const* source: m_sourceOrder)
 			for (ASTPointer<ASTNode> const& node: source->ast->nodes())
@@ -218,6 +224,7 @@ bool CompilerStack::analyze()
 
 		if (noErrors)
 		{
+			// Checks that can only be done when all types of all AST nodes are known.
 			PostTypeChecker postTypeChecker(m_errorReporter);
 			for (Source const* source: m_sourceOrder)
 				if (!postTypeChecker.check(*source->ast))
@@ -226,6 +233,8 @@ bool CompilerStack::analyze()
 
 		if (noErrors)
 		{
+			// Control flow graph generator and analyzer. It can check for issues such as
+			// variable is used before it is assigned to.
 			CFG cfg(m_errorReporter);
 			for (Source const* source: m_sourceOrder)
 				if (!cfg.constructFlow(*source->ast))
@@ -242,6 +251,7 @@ bool CompilerStack::analyze()
 
 		if (noErrors)
 		{
+			// Checks for common mistakes. Only generates warnings.
 			StaticAnalyzer staticAnalyzer(m_errorReporter);
 			for (Source const* source: m_sourceOrder)
 				if (!staticAnalyzer.analyze(*source->ast))
@@ -250,6 +260,7 @@ bool CompilerStack::analyze()
 
 		if (noErrors)
 		{
+			// Check for state mutability in every function.
 			vector<ASTPointer<ASTNode>> ast;
 			for (Source const* source: m_sourceOrder)
 				ast.push_back(source->ast);
@@ -300,6 +311,7 @@ bool CompilerStack::compile()
 		if (!parseAndAnalyze())
 			return false;
 
+	// Only compile contracts individually which have been requested.
 	map<ContractDefinition const*, eth::Assembly const*> compiledContracts;
 	for (Source const* source: m_sourceOrder)
 		for (ASTPointer<ASTNode> const& node: source->ast->nodes())
diff --git a/libsolidity/interface/CompilerStack.h b/libsolidity/interface/CompilerStack.h
index 0578ac863..7b1446602 100644
--- a/libsolidity/interface/CompilerStack.h
+++ b/libsolidity/interface/CompilerStack.h
@@ -352,8 +352,9 @@ private:
 	std::vector<Remapping> m_remappings;
 	std::map<std::string const, Source> m_sources;
 	std::shared_ptr<GlobalContext> m_globalContext;
-	std::map<ASTNode const*, std::shared_ptr<DeclarationContainer>> m_scopes;
 	std::vector<Source const*> m_sourceOrder;
+	/// This is updated during compilation.
+	std::map<ASTNode const*, std::shared_ptr<DeclarationContainer>> m_scopes;
 	std::map<std::string const, Contract> m_contracts;
 	ErrorList m_errorList;
 	ErrorReporter m_errorReporter;