Some documentation.

6 files changed, 31 insertions, 12 deletions

diff --git a/ASTPrinter.h b/ASTPrinter.h
index 14592e2b..74e0837f 100644
--- a/ASTPrinter.h
+++ b/ASTPrinter.h
@@ -30,6 +30,7 @@ namespace dev
 namespace solidity
 {
 
+/// Pretty-printer for the abstract syntax tree (the "pretty" is arguable) for debugging purposes.
 class ASTPrinter: public ASTVisitor
 {
 public:
diff --git a/ASTVisitor.h b/ASTVisitor.h
index 72f28768..a667ad39 100644
--- a/ASTVisitor.h
+++ b/ASTVisitor.h
@@ -30,13 +30,15 @@ namespace dev
 namespace solidity
 {
 
+/// Visitor interface for the abstract syntax tree. This class is tightly bound to the
+/// implementation of @ref ASTNode::accept and its overrides. After a call to
+/// @ref ASTNode::accept, the function visit for the appropriate parameter is called and then
+/// (if it returns true) this continues recursively for all child nodes in document order
+/// (there is an exception for contracts). After all child nodes have been visited, endVisit is
+/// called for the node.
 class ASTVisitor
 {
 public:
-	/// These functions are called after a call to ASTNode::accept,
-	/// first visit, then (if visit returns true) recursively for all
-	/// child nodes in document order (exception for contracts) and then
-	/// endVisit.
 	virtual bool visit(ASTNode&) { return true; }
 	virtual bool visit(ContractDefinition&) { return true; }
 	virtual bool visit(StructDefinition&) { return true; }
diff --git a/NameAndTypeResolver.cpp b/NameAndTypeResolver.cpp
index e9d90dc8..0f34eb4c 100644
--- a/NameAndTypeResolver.cpp
+++ b/NameAndTypeResolver.cpp
@@ -130,7 +130,7 @@ void DeclarationRegistrationHelper::enterNewSubScope(ASTNode& _node)
 void DeclarationRegistrationHelper::closeCurrentScope()
 {
 	BOOST_ASSERT(m_currentScope);
-	m_currentScope = m_currentScope->getOuterScope();
+	m_currentScope = m_currentScope->getEnclosingScope();
 }
 
 void DeclarationRegistrationHelper::registerDeclaration(Declaration& _declaration, bool _opensScope)
diff --git a/Scope.cpp b/Scope.cpp
index 4fcd2f45..540c4120 100644
--- a/Scope.cpp
+++ b/Scope.cpp
@@ -41,8 +41,8 @@ Declaration* Scope::resolveName(ASTString const& _name, bool _recursive) const
 	auto result = m_declarations.find(_name);
 	if (result != m_declarations.end())
 		return result->second;
-	if (_recursive && m_outerScope)
-		return m_outerScope->resolveName(_name, true);
+	if (_recursive && m_enclosingScope)
+		return m_enclosingScope->resolveName(_name, true);
 	return nullptr;
 }
 
diff --git a/Scope.h b/Scope.h
index 2e36e528..83b01f42 100644
--- a/Scope.h
+++ b/Scope.h
@@ -32,18 +32,20 @@ namespace dev
 namespace solidity
 {
 
+/// Container that stores mappings betwee names and declarations. It also contains a link to the
+/// enclosing scope.
 class Scope
 {
 public:
-	explicit Scope(Scope* _outerScope = nullptr): m_outerScope(_outerScope) {}
+	explicit Scope(Scope* _enclosingScope = nullptr): m_enclosingScope(_enclosingScope) {}
 	/// Registers the declaration in the scope unless its name is already declared. Returns true iff
 	/// it was not yet declared.
 	bool registerDeclaration(Declaration& _declaration);
 	Declaration* resolveName(ASTString const& _name, bool _recursive = false) const;
-	Scope* getOuterScope() const { return m_outerScope; }
+	Scope* getEnclosingScope() const { return m_enclosingScope; }
 
 private:
-	Scope* m_outerScope;
+	Scope* m_enclosingScope;
 	std::map<ASTString, Declaration*> m_declarations;
 };
 
diff --git a/Types.h b/Types.h
index db4b05a5..40bc4487 100644
--- a/Types.h
+++ b/Types.h
@@ -37,6 +37,7 @@ namespace solidity
 
 // @todo realMxN, string<N>, mapping
 
+/// Abstract base class that forms the root of the type hierarchy.
 class Type: private boost::noncopyable
 {
 public:
@@ -45,11 +46,15 @@ public:
 		INTEGER, BOOL, REAL, STRING, CONTRACT, STRUCT, FUNCTION, MAPPING, VOID, TYPE
 	};
 
-	//! factory functions that convert an AST TypeName to a Type.
+	///@{
+	///@name Factory functions
+	/// Factory functions that convert an AST @ref TypeName to a Type.
 	static std::shared_ptr<Type> fromElementaryTypeName(Token::Value _typeToken);
 	static std::shared_ptr<Type> fromUserDefinedTypeName(UserDefinedTypeName const& _typeName);
 	static std::shared_ptr<Type> fromMapping(Mapping const& _typeName);
+	/// @}
 
+	/// Auto-detect the proper type for a literal
 	static std::shared_ptr<Type> forLiteral(Literal const& _literal);
 
 	virtual Category getCategory() const = 0;
@@ -68,6 +73,7 @@ public:
 	virtual bytes literalToBigEndian(Literal const&) const { return NullBytes; }
 };
 
+/// Any kind of integer type including hash and address.
 class IntegerType: public Type
 {
 public:
@@ -101,6 +107,7 @@ private:
 	Modifier m_modifier;
 };
 
+/// The boolean type.
 class BoolType: public Type
 {
 public:
@@ -119,6 +126,7 @@ public:
 	virtual bytes literalToBigEndian(Literal const& _literal) const override;
 };
 
+/// The type of a contract instance, there is one distinct type for each contract definition.
 class ContractType: public Type
 {
 public:
@@ -133,6 +141,7 @@ private:
 	ContractDefinition const& m_contract;
 };
 
+/// The type of a struct instance, there is one distinct type per struct definition.
 class StructType: public Type
 {
 public:
@@ -151,6 +160,7 @@ private:
 	StructDefinition const& m_struct;
 };
 
+/// The type of a function, there is one distinct type per function definition.
 class FunctionType: public Type
 {
 public:
@@ -167,6 +177,7 @@ private:
 	FunctionDefinition const& m_function;
 };
 
+/// The type of a mapping, there is one distinct type per key/value type pair.
 class MappingType: public Type
 {
 public:
@@ -181,7 +192,8 @@ private:
 	std::shared_ptr<Type const> m_valueType;
 };
 
-//@todo should be changed into "empty anonymous struct"
+/// The void type, can only be implicitly used as the type that is returned by functions without
+/// return parameters.
 class VoidType: public Type
 {
 public:
@@ -191,6 +203,8 @@ public:
 	virtual std::string toString() const override { return "void"; }
 };
 
+/// The type of a type reference. The type of "uint32" when used in "a = uint32(2)" is an example
+/// of a TypeType.
 class TypeType: public Type
 {
 public: