From 92ee64f44323e0b90dfe4e441fef5fb4c21174c7 Mon Sep 17 00:00:00 2001 From: Christian Date: Thu, 23 Oct 2014 17:06:12 +0200 Subject: [PATCH] Some documentation. --- libsolidity/ASTPrinter.h | 1 + libsolidity/ASTVisitor.h | 10 ++++++---- libsolidity/NameAndTypeResolver.cpp | 2 +- libsolidity/Scope.cpp | 4 ++-- libsolidity/Scope.h | 8 +++++--- libsolidity/Types.h | 18 ++++++++++++++++-- 6 files changed, 31 insertions(+), 12 deletions(-) diff --git a/libsolidity/ASTPrinter.h b/libsolidity/ASTPrinter.h index 14592e2b9..74e0837ff 100644 --- a/libsolidity/ASTPrinter.h +++ b/libsolidity/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/libsolidity/ASTVisitor.h b/libsolidity/ASTVisitor.h index 72f287683..a667ad392 100644 --- a/libsolidity/ASTVisitor.h +++ b/libsolidity/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/libsolidity/NameAndTypeResolver.cpp b/libsolidity/NameAndTypeResolver.cpp index e9d90dc88..0f34eb4c5 100644 --- a/libsolidity/NameAndTypeResolver.cpp +++ b/libsolidity/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/libsolidity/Scope.cpp b/libsolidity/Scope.cpp index 4fcd2f45e..540c41204 100644 --- a/libsolidity/Scope.cpp +++ b/libsolidity/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/libsolidity/Scope.h b/libsolidity/Scope.h index 2e36e5281..83b01f423 100644 --- a/libsolidity/Scope.h +++ b/libsolidity/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 m_declarations; }; diff --git a/libsolidity/Types.h b/libsolidity/Types.h index db4b05a5a..40bc44876 100644 --- a/libsolidity/Types.h +++ b/libsolidity/Types.h @@ -37,6 +37,7 @@ namespace solidity // @todo realMxN, string, 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 fromElementaryTypeName(Token::Value _typeToken); static std::shared_ptr fromUserDefinedTypeName(UserDefinedTypeName const& _typeName); static std::shared_ptr fromMapping(Mapping const& _typeName); + /// @} + /// Auto-detect the proper type for a literal static std::shared_ptr 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 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: