Merge pull request #4327 from ethereum/document-internals

Properly explain all the analsys steps in CompilerStack

1 files changed, 13 insertions, 1 deletions

diff --git a/libsolidity/interface/CompilerStack.cpp b/libsolidity/interface/CompilerStack.cpp
index aa33bad8..32cb488f 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())