From 17f54705407ab95f8a0fdae5d41684de34b34b5c Mon Sep 17 00:00:00 2001 From: Christian Date: Tue, 28 Oct 2014 16:51:26 +0100 Subject: [PATCH] Asterisk-syntax for doxygen class documentation. --- libsolidity/AST.h | 140 ++++++++++++++++++++---------- libsolidity/ASTPrinter.h | 4 +- libsolidity/Compiler.h | 24 +++-- libsolidity/NameAndTypeResolver.h | 19 ++-- libsolidity/Scope.h | 6 +- libsolidity/Types.h | 40 ++++++--- solc/main.cpp | 4 +- 7 files changed, 162 insertions(+), 75 deletions(-) diff --git a/libsolidity/AST.h b/libsolidity/AST.h index 5c975ee4b..e66572800 100644 --- a/libsolidity/AST.h +++ b/libsolidity/AST.h @@ -41,9 +41,11 @@ namespace solidity class ASTVisitor; -/// The root (abstract) class of the AST inheritance tree. -/// It is possible to traverse all direct and indirect children of an AST node by calling -/// accept, providing an ASTVisitor. +/** + * The root (abstract) class of the AST inheritance tree. + * It is possible to traverse all direct and indirect children of an AST node by calling + * accept, providing an ASTVisitor. + */ class ASTNode: private boost::noncopyable { public: @@ -77,7 +79,9 @@ private: Location m_location; }; -/// Abstract AST class for a declaration (contract, function, struct, variable). +/** + * Abstract AST class for a declaration (contract, function, struct, variable). + */ class Declaration: public ASTNode { public: @@ -91,9 +95,11 @@ private: ASTPointer m_name; }; -/// Definition of a contract. This is the only AST nodes where child nodes are not visited in -/// document order. It first visits all struct declarations, then all variable declarations and -/// finally all function declarations. +/** + * Definition of a contract. This is the only AST nodes where child nodes are not visited in + * document order. It first visits all struct declarations, then all variable declarations and + * finally all function declarations. + */ class ContractDefinition: public Declaration { public: @@ -133,9 +139,11 @@ private: std::vector> m_members; }; -/// Parameter list, used as function parameter list and return list. -/// None of the parameters is allowed to contain mappings (not even recursively -/// inside structs), but (@todo) this is not yet enforced. +/** + * Parameter list, used as function parameter list and return list. + * None of the parameters is allowed to contain mappings (not even recursively + * inside structs), but (@todo) this is not yet enforced. + */ class ParameterList: public ASTNode { public: @@ -178,8 +186,10 @@ private: ASTPointer m_body; }; -/// Declaration of a variable. This can be used in various places, e.g. in function parameter -/// lists, struct definitions and even function bodys. +/** + * Declaration of a variable. This can be used in various places, e.g. in function parameter + * lists, struct definitions and even function bodys. + */ class VariableDeclaration: public Declaration { public: @@ -205,7 +215,9 @@ private: /// Types /// @{ -/// Abstract base class of a type name, can be any built-in or user-defined type. +/** + * Abstract base class of a type name, can be any built-in or user-defined type. + */ class TypeName: public ASTNode { public: @@ -217,8 +229,10 @@ public: virtual std::shared_ptr toType() = 0; }; -/// Any pre-defined type name represented by a single keyword, i.e. it excludes mappings, -/// contracts, functions, etc. +/** + * Any pre-defined type name represented by a single keyword, i.e. it excludes mappings, + * contracts, functions, etc. + */ class ElementaryTypeName: public TypeName { public: @@ -233,8 +247,10 @@ private: Token::Value m_type; }; -/// Name referring to a user-defined type (i.e. a struct). -/// @todo some changes are necessary if this is also used to refer to contract types later +/** + * Name referring to a user-defined type (i.e. a struct). + * @todo some changes are necessary if this is also used to refer to contract types later + */ class UserDefinedTypeName: public TypeName { public: @@ -253,7 +269,9 @@ private: StructDefinition* m_referencedStruct; }; -/// A mapping type. Its source form is "mapping('keyType' => 'valueType')" +/** + * A mapping type. Its source form is "mapping('keyType' => 'valueType')" + */ class Mapping: public TypeName { public: @@ -274,7 +292,9 @@ private: /// @{ -/// Abstract base class for statements. +/** + * Abstract base class for statements. + */ class Statement: public ASTNode { public: @@ -292,7 +312,9 @@ protected: void expectType(Expression& _expression, Type const& _expectedType); }; -/// Brace-enclosed block containing zero or more statements. +/** + * Brace-enclosed block containing zero or more statements. + */ class Block: public Statement { public: @@ -306,8 +328,10 @@ private: std::vector> m_statements; }; -/// If-statement with an optional "else" part. Note that "else if" is modeled by having a new -/// if-statement as the false (else) body. +/** + * If-statement with an optional "else" part. Note that "else if" is modeled by having a new + * if-statement as the false (else) body. + */ class IfStatement: public Statement { public: @@ -324,8 +348,10 @@ private: ASTPointer m_falseBody; //< "else" part, optional }; -/// Statement in which a break statement is legal. -/// @todo actually check this requirement. +/** + * Statement in which a break statement is legal. + * @todo actually check this requirement. + */ class BreakableStatement: public Statement { public: @@ -380,9 +406,11 @@ private: ParameterList* m_returnParameters; }; -/// Definition of a variable as a statement inside a function. It requires a type name (which can -/// also be "var") but the actual assignment can be missing. -/// Examples: var a = 2; uint256 a; +/** + * Definition of a variable as a statement inside a function. It requires a type name (which can + * also be "var") but the actual assignment can be missing. + * Examples: var a = 2; uint256 a; + */ class VariableDefinition: public Statement { public: @@ -397,8 +425,10 @@ private: ASTPointer m_value; ///< the assigned value, can be missing }; -/// An expression, i.e. something that has a value (which can also be of type "void" in case -/// of function calls). +/** + * An expression, i.e. something that has a value (which can also be of type "void" in case + * of function calls). + */ class Expression: public Statement { public: @@ -416,8 +446,10 @@ protected: /// Expressions /// @{ -/// Assignment, can also be a compound assignment. -/// Examples: (a = 7 + 8) or (a *= 2) +/** + * Assignment, can also be a compound assignment. + * Examples: (a = 7 + 8) or (a *= 2) + */ class Assignment: public Expression { public: @@ -438,8 +470,10 @@ private: ASTPointer m_rightHandSide; }; -/// Operation involving a unary operator, pre- or postfix. -/// Examples: ++i, delete x or !true +/** + * Operation involving a unary operator, pre- or postfix. + * Examples: ++i, delete x or !true + */ class UnaryOperation: public Expression { public: @@ -459,8 +493,10 @@ private: bool m_isPrefix; }; -/// Operation involving a binary operator. -/// Examples: 1 + 2, true && false or 1 <= 4 +/** + * Operation involving a binary operator. + * Examples: 1 + 2, true && false or 1 <= 4 + */ class BinaryOperation: public Expression { public: @@ -482,7 +518,9 @@ private: std::shared_ptr m_commonType; }; -/// Can be ordinary function call, type cast or struct construction. +/** + * Can be ordinary function call, type cast or struct construction. + */ class FunctionCall: public Expression { public: @@ -501,7 +539,9 @@ private: std::vector> m_arguments; }; -/// Access to a member of an object. Example: x.name +/** + * Access to a member of an object. Example: x.name + */ class MemberAccess: public Expression { public: @@ -517,7 +557,9 @@ private: ASTPointer m_memberName; }; -/// Index access to an array. Example: a[2] +/** + * Index access to an array. Example: a[2] + */ class IndexAccess: public Expression { public: @@ -532,15 +574,19 @@ private: ASTPointer m_index; }; -/// Primary expression, i.e. an expression that cannot be divided any further. Examples are literals -/// or variable references. +/** + * Primary expression, i.e. an expression that cannot be divided any further. Examples are literals + * or variable references. + */ class PrimaryExpression: public Expression { public: PrimaryExpression(Location const& _location): Expression(_location) {} }; -/// An identifier, i.e. a reference to a declaration by name like a variable or function. +/** + * An identifier, i.e. a reference to a declaration by name like a variable or function. + */ class Identifier: public PrimaryExpression { public: @@ -561,9 +607,11 @@ private: Declaration* m_referencedDeclaration; }; -/// An elementary type name expression is used in expressions like "a = uint32(2)" to change the -/// type of an expression explicitly. Here, "uint32" is the elementary type name expression and -/// "uint32(2)" is a @ref FunctionCall. +/** + * An elementary type name expression is used in expressions like "a = uint32(2)" to change the + * type of an expression explicitly. Here, "uint32" is the elementary type name expression and + * "uint32(2)" is a @ref FunctionCall. + */ class ElementaryTypeNameExpression: public PrimaryExpression { public: @@ -578,7 +626,9 @@ private: Token::Value m_typeToken; }; -/// A literal string or number. @see Type::literalToBigEndian is used to actually parse its value. +/** + * A literal string or number. @see Type::literalToBigEndian is used to actually parse its value. + */ class Literal: public PrimaryExpression { public: diff --git a/libsolidity/ASTPrinter.h b/libsolidity/ASTPrinter.h index 74e0837ff..97256c056 100644 --- a/libsolidity/ASTPrinter.h +++ b/libsolidity/ASTPrinter.h @@ -30,7 +30,9 @@ namespace dev namespace solidity { -/// Pretty-printer for the abstract syntax tree (the "pretty" is arguable) for debugging purposes. +/** + * Pretty-printer for the abstract syntax tree (the "pretty" is arguable) for debugging purposes. + */ class ASTPrinter: public ASTVisitor { public: diff --git a/libsolidity/Compiler.h b/libsolidity/Compiler.h index ac5e10ec9..1401e12e3 100644 --- a/libsolidity/Compiler.h +++ b/libsolidity/Compiler.h @@ -28,9 +28,11 @@ namespace dev { namespace solidity { -/// A single item of compiled code that can be assembled to a single byte value in the final -/// bytecode. Its main purpose is to inject jump labels and label references into the opcode stream, -/// which can be resolved in the final step. +/** + * A single item of compiled code that can be assembled to a single byte value in the final + * bytecode. Its main purpose is to inject jump labels and label references into the opcode stream, + * which can be resolved in the final step. + */ class AssemblyItem { public: @@ -64,9 +66,11 @@ private: using AssemblyItems = std::vector; -/// Context to be shared by all units that compile the same contract. Its current usage only -/// concerns dispensing unique jump label IDs and storing their actual positions in the bytecode -/// stream. +/** + * Context to be shared by all units that compile the same contract. Its current usage only + * concerns dispensing unique jump label IDs and storing their actual positions in the bytecode + * stream. + */ class CompilerContext { public: @@ -81,9 +85,11 @@ private: std::map m_labelPositions; }; -/// Compiler for expressions, i.e. converts an AST tree whose root is an Expression into a stream -/// of EVM instructions. It needs a compiler context that is the same for the whole compilation -/// unit. +/** + * Compiler for expressions, i.e. converts an AST tree whose root is an Expression into a stream + * of EVM instructions. It needs a compiler context that is the same for the whole compilation + * unit. + */ class ExpressionCompiler: public ASTVisitor { public: diff --git a/libsolidity/NameAndTypeResolver.h b/libsolidity/NameAndTypeResolver.h index 055835c4f..bb7fcb98f 100644 --- a/libsolidity/NameAndTypeResolver.h +++ b/libsolidity/NameAndTypeResolver.h @@ -33,8 +33,11 @@ namespace dev namespace solidity { -/// Resolves name references, resolves all types and checks that all operations are valid for the -/// inferred types. An exception is throw on the first error. +/** + * Resolves name references, types and checks types of all expressions. + * Specifically, it checks that all operations are valid for the inferred types. + * An exception is throw on the first error. + */ class NameAndTypeResolver: private boost::noncopyable { public: @@ -53,8 +56,10 @@ private: Scope* m_currentScope; }; -/// Traverses the given AST upon construction and fills _scopes with all declarations inside the -/// AST. +/** + * Traverses the given AST upon construction and fills _scopes with all declarations inside the + * AST. + */ class DeclarationRegistrationHelper: private ASTVisitor { public: @@ -78,8 +83,10 @@ private: Scope* m_currentScope; }; -/// Resolves references to declarations (of variables and types) and also establishes the link -/// between a return statement and the return parameter list. +/** + * Resolves references to declarations (of variables and types) and also establishes the link + * between a return statement and the return parameter list. + */ class ReferencesResolver: private ASTVisitor { public: diff --git a/libsolidity/Scope.h b/libsolidity/Scope.h index 83b01f423..637c2d5ce 100644 --- a/libsolidity/Scope.h +++ b/libsolidity/Scope.h @@ -32,8 +32,10 @@ namespace dev namespace solidity { -/// Container that stores mappings betwee names and declarations. It also contains a link to the -/// enclosing scope. +/** + * Container that stores mappings betwee names and declarations. It also contains a link to the + * enclosing scope. + */ class Scope { public: diff --git a/libsolidity/Types.h b/libsolidity/Types.h index 4d56b5abb..c9f6da574 100644 --- a/libsolidity/Types.h +++ b/libsolidity/Types.h @@ -36,7 +36,9 @@ namespace solidity // @todo realMxN, string, mapping -/// Abstract base class that forms the root of the type hierarchy. +/** + * Abstract base class that forms the root of the type hierarchy. + */ class Type: private boost::noncopyable { public: @@ -72,7 +74,9 @@ public: virtual bytes literalToBigEndian(Literal const&) const { return NullBytes; } }; -/// Any kind of integer type including hash and address. +/** + * Any kind of integer type including hash and address. + */ class IntegerType: public Type { public: @@ -106,7 +110,9 @@ private: Modifier m_modifier; }; -/// The boolean type. +/** + * The boolean type. + */ class BoolType: public Type { public: @@ -125,7 +131,9 @@ public: virtual bytes literalToBigEndian(Literal const& _literal) const override; }; -/// The type of a contract instance, there is one distinct type for each contract definition. +/** + * The type of a contract instance, there is one distinct type for each contract definition. + */ class ContractType: public Type { public: @@ -140,7 +148,9 @@ private: ContractDefinition const& m_contract; }; -/// The type of a struct instance, there is one distinct type per struct definition. +/** + * The type of a struct instance, there is one distinct type per struct definition. + */ class StructType: public Type { public: @@ -159,7 +169,9 @@ private: StructDefinition const& m_struct; }; -/// The type of a function, there is one distinct type per function definition. +/** + * The type of a function, there is one distinct type per function definition. + */ class FunctionType: public Type { public: @@ -176,7 +188,9 @@ private: FunctionDefinition const& m_function; }; -/// The type of a mapping, there is one distinct type per key/value type pair. +/** + * The type of a mapping, there is one distinct type per key/value type pair. + */ class MappingType: public Type { public: @@ -191,8 +205,10 @@ private: std::shared_ptr m_valueType; }; -/// The void type, can only be implicitly used as the type that is returned by functions without -/// return parameters. +/** + * The void type, can only be implicitly used as the type that is returned by functions without + * return parameters. + */ class VoidType: public Type { public: @@ -202,8 +218,10 @@ 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. +/** + * 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: diff --git a/solc/main.cpp b/solc/main.cpp index 221ab962e..33e8db794 100644 --- a/solc/main.cpp +++ b/solc/main.cpp @@ -36,7 +36,9 @@ void version() } -/// Helper class that extracts the first expression in an AST. +/** + * Helper class that extracts the first expression in an AST. + */ class FirstExpressionExtractor: private ASTVisitor { public: