docs: document AST nodes

furc/include/furc/ast/declaration.hpp

@@ -8,30 +8,69 @@
 namespace furc {
 namespace ast {
 
+/**
+ * @brief Declaration node type.
+ */
 enum class declaration_node_t {
-    FunctionDeclaration,
+    Func,    /**< Function declaration. */
-    FunctionDefinition,
+    FuncDef, /**< Function definition. */
 };
 
+/**
+ * @brief Declaration AST node interface.
+ */
 class declaration_node : public statement_node {
 public:
+    /**
+     * @brief Returns this node's category.
+     *
+     * @return node_t::Declaration.
+     */
     node_t category() const override { return node_t::Declaration; }
 
-    statement_node_t statement_type() const override { return statement_node_t::Declaration; }
+    /**
+     * @brief Returns this node's statement type.
+     *
+     * @return statement_node_t::Declaration.
+     */
+    statement_node_t statement_type() const final { return statement_node_t::Declaration; }
 
+    /**
+     * @brief Returns this node's declaration type.
+     *
+     * @return The declaration type.
+     */
     virtual declaration_node_t declaration_type() const = 0;
 protected:
     bool equal(const node& rhs) const override;
 };
 
+/**
+ * @brief Function declaration AST node.
+ */
 class function_declaration_node : public declaration_node {
 public:
+    /**
+     * @brief Construct a new function declaration node object from name token.
+     *
+     * @param name Name of the function.
+     */
     function_declaration_node(front::token name)
-      : m_name(name) {}
+      : p_name(name) {}
 public:
-    declaration_node_t declaration_type() const override { return declaration_node_t::FunctionDeclaration; }
+    /**
+     * @brief Returns this node's declaration type.
+     *
+     * @return declaration_node_t::FunctionDeclaration.
+     */
+    declaration_node_t declaration_type() const override { return declaration_node_t::Func; }
 
-    front::token name() const { return m_name; }
+    /**
+     * @brief Returns function's name.
+     *
+     * @return Name of the function.
+     */
+    front::token name() const { return p_name; }
 public:
     void accept(visitor& visitor) const override;
 
@@ -39,16 +78,38 @@ public:
 protected:
     bool equal(const node& rhs) const override;
 protected:
-    front::token m_name;
+    /**
+     * @brief Name of the function.
+     */
+    front::token p_name;
 };
 
+/**
+ * @brief Function definition AST node.
+ */
 class function_definition_node final : public function_declaration_node {
 public:
+    /**
+     * @brief Construct a new function definition node object from name and body.
+     *
+     * @param name Name of the function.
+     * @param body Body of the function.
+     */
     function_definition_node(front::token name, body_h&& body)
       : function_declaration_node(name), m_body(std::move(body)) {}
 public:
-    declaration_node_t declaration_type() const override { return declaration_node_t::FunctionDefinition; }
+    /**
+     * @brief Returns this node's declaration type.
+     *
+     * @return declaration_node_t::FunctionDefinition.
+     */
+    declaration_node_t declaration_type() const override { return declaration_node_t::FuncDef; }
 
+    /**
+     * @brief Returns function's body.
+     *
+     * @return Body of the function.
+     */
     const body_h& body() const { return m_body; }
 public:
     void accept(visitor& visitor) const override;

furc/include/furc/ast/expression.hpp

@@ -7,34 +7,78 @@
 namespace furc {
 namespace ast {
 
+/**
+ * @brief Expression node type.
+ */
 enum class expression_node_t {
-    Literal,
+    Literal,   /**< Literal */
-    VarRead,
+    VarRead,   /**< Variable read expression */
-    VarAssign,
+    Unaryop,   /**< Unary operation expression */
-    Unaryop,
+    Binop,     /**< Binary operation expression */
-    Binop,
+    VarAssign, /**< Variable assignment expression */
-    Paren,
 };
 
+/**
+ * @brief Expression AST node.
+ */
 class expression_node : public statement_node {
 public:
+    /**
+     * @brief Returns this node's category.
+     *
+     * @return node_t::Expression.
+     */
     node_t category() const override { return node_t::Expression; }
 
+    /**
+     * @brief Returns this node's statement type.
+     *
+     * @return statement_node_t::Expression.
+     */
     statement_node_t statement_type() const override { return statement_node_t::Expression; }
 
+    /**
+     * @brief Returns this node's expression type.
+     *
+     * @return The expression type.
+     */
     virtual expression_node_t expression_type() const = 0;
 protected:
     bool equal(const node& rhs) const override;
 };
 
+/**
+ * @brief Var read expression AST node.
+ */
 class var_read_expression_node final : public expression_node {
 public:
+    /**
+     * @brief Construct a new var read expression node object from a name handle.
+     *
+     * @param name Handle to the name.
+     */
     var_read_expression_node(handle<std::string_view>&& name)
       : m_name(std::move(name)) {}
 
+    /**
+     * @brief Returns the variable's name.
+     *
+     * @return Name of the variable.
+     */
     const handle<std::string_view>& get_name() const { return m_name; }
-    handle<std::string_view>&&      move_name() { return std::move(m_name); }
+
+    /**
+     * @brief Returns the variable's name.
+     *
+     * @return Name of the variable.
+     */
+    handle<std::string_view>&& move_name() { return std::move(m_name); }
 public:
+    /**
+     * @brief Returns this node's expression type.
+     *
+     * @return expression_node_t::VarRead.
+     */
     expression_node_t expression_type() const override { return expression_node_t::VarRead; }
 public:
     void accept(visitor& visitor) const override;
@@ -46,27 +90,72 @@ private:
     handle<std::string_view> m_name;
 };
 
+/**
+ * @brief Unary operation node type.
+ */
 enum class unaryop_expression_node_t {
-    Positive,
+    Positive,         /**< Positive (unary plus) */
-    Negative,
+    Negative,         /**< Negative (unary minus) */
-    PrefixIncrement,
+    PrefixIncrement,  /**< Prefix increment */
-    PostfixIncrement,
+    PostfixIncrement, /**< Postfix increment */
-    PrefixDecrement,
+    PrefixDecrement,  /**< Prefix decrement */
-    PostfixDecrement,
+    PostfixDecrement, /**< Postfix decrement */
 };
 
+/**
+ * @brief Unary operation expression AST node.
+ */
 class unaryop_expression_node final : public expression_node {
 public:
+    /**
+     * @brief Construct a new unaryop expression node object from type and expression node handle.
+     *
+     * @param type Operation type.
+     * @param node Handle to the inner expression node.
+     */
     unaryop_expression_node(unaryop_expression_node_t type, expression_node_h&& node)
       : m_type(type), m_node(std::move(node)) {}
 
+    /**
+     * @brief Sets this node's inner expression.
+     *
+     * @param node New node handle.
+     */
     void set_node(expression_node_h&& node) { m_node = std::move(node); }
 
+    /**
+     * @brief Returns the type of this node's operation.
+     *
+     * @return The operation type.
+     */
     unaryop_expression_node_t type() const { return m_type; }
-    const expression_node_h&  get_node() const { return m_node; }
+
-    expression_node_h&        get_node() { return m_node; }
+    /**
-    expression_node_h&&       move_node() { return std::move(m_node); }
+     * @brief Returns this node's inner expression.
+     *
+     * @return The inner expression.
+     */
+    const expression_node_h& get_node() const { return m_node; }
+
+    /**
+     * @brief Returns this node's inner expression.
+     *
+     * @return The inner expression.
+     */
+    expression_node_h& get_node() { return m_node; }
+
+    /**
+     * @brief Moves this node's inner expression.
+     *
+     * @return The moved inner expression.
+     */
+    expression_node_h&& move_node() { return std::move(m_node); }
 public:
+    /**
+     * @brief Returns this node's expression type.
+     *
+     * @return expression_node_t::Unaryop.
+     */
     expression_node_t expression_type() const override { return expression_node_t::Unaryop; }
 public:
     void accept(visitor& visitor) const override;
@@ -76,37 +165,91 @@ protected:
     bool equal(const node& rhs) const override;
 private:
     unaryop_expression_node_t m_type;
-    expression_node_h         m_node;
+    expression_node_h         m_node; /**< The inner expression. */
 };
 
+/**
+ * @brief Binary operation expression node type.
+ */
 enum class binop_expression_node_t {
-    None = 0,
+    None = 0, /**< None */
-    Add,
+    Add,      /**< Addition */
-    Sub,
+    Sub,      /**< Subtraction */
-    Mul,
+    Mul,      /**< Multiplication */
-    Div,
+    Div,      /**< Division */
-    Mod,
+    Mod,      /**< Modulo */
 
-    Equal,
+    Equal,        /**< Equality */
-    NotEqual,
+    NotEqual,     /**< Inequality */
-    LessThan,
+    LessThan,     /**< Less */
-    GreaterThan,
+    GreaterThan,  /**< Greater */
-    LessEqual,
+    LessEqual,    /**< Less or equal */
-    GreaterEqual,
+    GreaterEqual, /**< Greater or equal */
 };
 
+/**
+ * @brief Binary operation expression AST node.
+ */
 class binop_expression_node final : public expression_node {
 public:
+    /**
+     * @brief Construct a new binary operation expression AST node.
+     *
+     * @param type Binary operation type.
+     * @param lhs Left-hand-side expression.
+     * @param rhs Right-hand-side expression.
+     */
     binop_expression_node(binop_expression_node_t type, expression_node_h&& lhs, expression_node_h&& rhs)
       : m_type(type), m_lhs(std::move(lhs)), m_rhs(std::move(rhs)) {}
 
-    binop_expression_node_t  type() const { return m_type; };
+    /**
+     * @brief Returns this node's binary operation type.
+     *
+     * @return The binary operation type.
+     */
+    binop_expression_node_t type() const { return m_type; };
+
+    /**
+     * @brief Returns this node's left-hand-side expression.
+     *
+     * @return The left-hand-side expression.
+     */
     const expression_node_h& lhs() const { return m_lhs; };
-    expression_node_h&       lhs() { return m_lhs; };
+
-    expression_node_h&&      move_lhs() { return std::move(m_lhs); };
+    /**
+     * @brief Returns this node's left-hand-side expression.
+     *
+     * @return The left-hand-side expression.
+     */
+    expression_node_h& lhs() { return m_lhs; };
+
+    /**
+     * @brief Moves this node's left-hand-side expression.
+     *
+     * @return The moved left-hand-side expression.
+     */
+    expression_node_h&& move_lhs() { return std::move(m_lhs); };
+
+    /**
+     * @brief Returns this node's right-hand-side expression.
+     *
+     * @return The right-hand-side expression.
+     */
     const expression_node_h& rhs() const { return m_rhs; };
-    expression_node_h&       rhs() { return m_rhs; };
+
-    expression_node_h&&      move_rhs() { return std::move(m_rhs); };
+    /**
+     * @brief Returns this node's right-hand-side expression.
+     *
+     * @return The right-hand-side expression.
+     */
+    expression_node_h& rhs() { return m_rhs; };
+
+    /**
+     * @brief Moves this node's right-hand-side expression.
+     *
+     * @return The moved right-hand-side expression.
+     */
+    expression_node_h&& move_rhs() { return std::move(m_rhs); };
 public:
     expression_node_t expression_type() const override { return expression_node_t::Binop; }
 public:
@@ -121,18 +264,56 @@ private:
     expression_node_h       m_rhs;
 };
 
+/**
+ * @brief Variable assignment expression AST node.
+ */
 class var_assign_expression_node final : public expression_node {
 public:
+    /**
+     * @brief Construct a new variable assignment expression AST node.
+     *
+     * @param lhs Left-hand-side expression handle.
+     * @param rhs Right-hand-side expression handle.
+     */
     var_assign_expression_node(expression_node_h&& lhs, expression_node_h&& rhs)
       : m_compound(binop_expression_node_t::None), m_lhs(std::move(lhs)), m_rhs(std::move(rhs)) {}
 
+    /**
+     * @brief Construct a new compound variable assignment expression AST node.
+     *
+     * @param compound Compound operation type.
+     * @param lhs Left-hand-side expression handle.
+     * @param rhs Right-hand-side expression handle.
+     */
     var_assign_expression_node(binop_expression_node_t compound, expression_node_h&& lhs, expression_node_h&& rhs)
       : m_compound(compound), m_lhs(std::move(lhs)), m_rhs(std::move(rhs)) {}
 
-    binop_expression_node_t  compound() const { return m_compound; }
+    /**
+     * @brief Returns this node's compound operation type.
+     *
+     * @return The compound operation type.
+     */
+    binop_expression_node_t compound() const { return m_compound; }
+
+    /**
+     * @brief Returns this node's left-hand-side expression.
+     *
+     * @return The left-hand-side expression.
+     */
     const expression_node_h& lhs() const { return m_lhs; }
+
+    /**
+     * @brief Returns this node's right-hand-side expression.
+     *
+     * @return The right-hand-side expression.
+     */
     const expression_node_h& rhs() const { return m_rhs; }
 public:
+    /**
+     * @brief Returns this node's expression type.
+     *
+     * @return expression_node_t::VarAssign.
+     */
     expression_node_t expression_type() const override { return expression_node_t::VarAssign; }
 public:
     void accept(visitor& visitor) const override;

furc/include/furc/ast/fwd.hpp

@@ -7,63 +7,201 @@
 #include <vector>
 
 namespace furc {
+
+/**
+ * @brief Abstract Syntax Tree definitions.
+ */
 namespace ast {
 
 class node;
 
+/**
+ * @brief Alias for handle to node.
+ *
+ * @tparam T AST node type.
+ */
 template <typename T>
 using node_handle = handle<T*, std::string>;
 
 class literal_node;
+
+/**
+ * @brief Alias for handle to literal_node.
+ * @see literal_node
+ */
 using literal_node_h = node_handle<literal_node>;
+
 class expression_node;
+
+/**
+ * @brief Alias for handle to expression_node.
+ * @see expression_node
+ */
 using expression_node_h = node_handle<expression_node>;
+
 class declaration_node;
+
+/**
+ * @brief Alias for handle to declaration_node.
+ * @see declaration_node
+ */
 using declaration_node_h = node_handle<declaration_node>;
+
 class statement_node;
+
+/**
+ * @brief Alias for handle to statement_node.
+ * @see statement_node
+ */
 using statement_node_h = node_handle<statement_node>;
+
 class program_node;
+
+/**
+ * @brief Alias for handle to program_node.
+ * @see program_node
+ */
 using program_node_h = node_handle<program_node>;
 
 class string_literal_node;
+
+/**
+ * @brief Alias for handle to string_literal_node.
+ * @see string_literal_node
+ */
 using string_literal_node_h = node_handle<string_literal_node>;
+
 class integer_literal_node;
+
+/**
+ * @brief Alias for handle to integer_literal_node.
+ * @see integer_literal_node
+ */
 using integer_literal_node_h = node_handle<integer_literal_node>;
 
 class var_read_expression_node;
+
+/**
+ * @brief Alias for handle to var_read_expression_node.
+ * @see var_read_expression_node
+ */
 using var_read_expression_node_h = node_handle<var_read_expression_node>;
+
 class unaryop_expression_node;
+
+/**
+ * @brief Alias for handle to unaryop_expression_node.
+ * @see unaryop_expression_node
+ */
 using unaryop_expression_node_h = node_handle<unaryop_expression_node>;
+
 class binop_expression_node;
+
+/**
+ * @brief Alias for handle to binop_expression_node.
+ * @see binop_expression_node
+ */
 using binop_expression_node_h = node_handle<binop_expression_node>;
+
 class var_assign_expression_node;
+
+/**
+ * @brief Alias for handle to var_assign_expression_node.
+ * @see var_assign_expression_node
+ */
 using var_assign_expression_node_h = node_handle<var_assign_expression_node>;
 
+/**
+ * @brief List of statements.
+ */
 struct body {
-    location                      begin, end;
+    /**
+     * @brief Location of the opening curly.
+     */
+    location begin;
+
+    /**
+     * @brief Location of the closing curly.
+     */
+    location end;
+
+    /**
+     * @brief List of statements.
+     */
     std::vector<statement_node_h> statements;
 
+    /**
+     * @brief Compares two bodies for equality.
+     *
+     * @param rhs Body to compare against.
+     * @return true if the bodies are equal.
+     */
     bool operator==(const body& rhs) const {
         return begin == rhs.begin && end == rhs.end && statements == rhs.statements;
     }
 
+    /**
+     * @brief Compares two bodies for inequality.
+     *
+     * @param rhs Body to compare against.
+     * @return true if the bodies are not equal.
+     */
     bool operator!=(const body& rhs) const { return !this->operator==(rhs); }
 
-    friend std::ostream& operator<<(std::ostream&, const body&);
+    /**
+     * @brief Prints a body to an output stream.
+     *
+     * @param os Output stream.
+     * @param body Body to print.
+     * @return The output stream.
+     */
+    friend std::ostream& operator<<(std::ostream& os, const body& body);
 };
 
+/**
+ * @brief Alias for handle to body.
+ * @see body
+ */
 using body_h = handle<body>;
 
 class function_declaration_node;
+
+/**
+ * @brief Alias for handle to function_declaration_node.
+ * @see function_declaration_node
+ */
 using function_declaration_node_h = node_handle<function_declaration_node>;
+
 class function_definition_node;
+
+/**
+ * @brief Alias for handle to function_definition_node.
+ * @see function_definition_node
+ */
 using function_definition_node_h = node_handle<function_definition_node>;
 
 class return_statement_node;
+
+/**
+ * @brief Alias for handle to return_statement_node.
+ * @see return_statement_node
+ */
 using return_statement_node_h = node_handle<return_statement_node>;
+
 class if_statement_node;
+
+/**
+ * @brief Alias for handle to if_statement_node.
+ * @see if_statement_node
+ */
 using if_statement_node_h = node_handle<if_statement_node>;
+
 class compound_statement_node;
+
+/**
+ * @brief Alias for handle to compound_statement_node.
+ * @see compound_statement_node
+ */
 using compound_statement_node_h = node_handle<compound_statement_node>;
 
 } // namespace ast

furc/include/furc/ast/literal.hpp

@@ -8,29 +8,68 @@
 namespace furc {
 namespace ast {
 
+/**
+ * @brief Literal node type.
+ */
 enum class literal_node_t {
-    String,
+    String,  /**< String literal. */
-    Integer
+    Integer, /**< Integer literal. */
 };
 
+/**
+ * @brief Literal AST node.
+ */
 class literal_node : public expression_node {
 public:
+    /**
+     * @brief Returns this node's category.
+     *
+     * @return node_t::Literal.
+     */
     node_t category() const override { return node_t::Literal; }
 
+    /**
+     * @brief Returns this node's expression type.
+     *
+     * @return expression_node_t::Literal.
+     */
     expression_node_t expression_type() const override { return expression_node_t::Literal; }
 
+    /**
+     * @brief Returns this node's literal type.
+     *
+     * @return The literal type.
+     */
     virtual literal_node_t literal_type() const = 0;
 protected:
     bool equal(const node& rhs) const override;
 };
 
+/**
+ * @brief String literal AST node.
+ */
 class string_literal_node final : public literal_node {
 public:
+    /**
+     * @brief Construct a new string literal node object from a handle.
+     *
+     * @param value A handle to value.
+     */
     string_literal_node(handle<std::string_view>&& value)
       : m_value(std::move(value)) {}
 public:
+    /**
+     * @brief Returns this node's literal type.
+     *
+     * @return literal_node_t::String.
+     */
     literal_node_t literal_type() const override { return literal_node_t::String; }
 
+    /**
+     * @brief Returns this node's value.
+     *
+     * @return A handle to the value.
+     */
     const handle<std::string_view>& value() const { return m_value; }
 public:
     void accept(visitor& visitor) const override;
@@ -42,15 +81,39 @@ private:
     handle<std::string_view> m_value;
 };
 
+/**
+ * @brief Integer literal AST node.
+ */
 class integer_literal_node final : public literal_node {
 public:
+    /**
+     * @brief Construct a new integer literal node object from a handle.
+     *
+     * @param value A handle to the value.
+     */
     integer_literal_node(handle<front::integer_token>&& value)
       : m_value(std::move(value)) {}
 public:
+    /**
+     * @brief Returns this node's literal type.
+     *
+     * @return literal_node_t::Integer.
+     */
     literal_node_t literal_type() const override { return literal_node_t::Integer; }
 
+    /**
+     * @brief Returns this node's value.
+     *
+     * @return A handle to the value.
+     */
     const handle<front::integer_token>& value() const { return m_value; }
 
+    /**
+     * @brief Compares this node with an integer token for equality.
+     *
+     * @param integer Integer token to compare against.
+     * @return true if the integer token is equal to this node.
+     */
     bool operator==(front::integer_token integer) const { return m_value == integer; }
 public:
     void accept(visitor& visitor) const override;

furc/include/furc/ast/node.hpp

@@ -7,14 +7,24 @@
 namespace furc {
 namespace ast {
 
+/**
+ * @brief Node category.
+ */
 enum class node_t {
-    Literal,
+    Literal,     /**< Literal. */
-    Expression,
+    Expression,  /**< Expression. */
-    Statement,
+    Statement,   /**< Statement. */
-    Declaration,
+    Declaration, /**< Declaration. */
-    Program,
+    Program,     /**< Program. */
 };
 
+/**
+ * @brief Prints a node type (category) to an output stream.
+ *
+ * @param os Output stream.
+ * @param type Type to print.
+ * @return The output stream.
+ */
 static inline std::ostream& operator<<(std::ostream& os, node_t type) {
     switch (type) {
     case node_t::Literal: return os << "literal";
@@ -23,29 +33,98 @@ static inline std::ostream& operator<<(std::ostream& os, node_t type) {
     case node_t::Declaration: return os << "declaration";
     case node_t::Program: return os << "program";
     }
+    return os;
 }
 
+/**
+ * @brief AST node interface.
+ */
 class node {
 public:
     node()          = default;
     virtual ~node() = default;
 
-    node(node&&)                 = default;
+    /**
-    node(const node&)            = delete;
+     * @brief Move constructor.
-    node& operator=(node&&)      = default;
+     *
-    node& operator=(const node&) = delete;
+     * Constructs a node by transferring the state of another node.
+     *
+     * @param other Node to move from.
+     */
+    node(node&& other) = default;
+    node(const node&)  = delete;
+
+    /**
+     * @brief Move constructor.
+     *
+     * Constructs a node by transferring the state of another node.
+     *
+     * @param other Node to move from.
+     */
+    node& operator=(node&& other) = default;
+    node& operator=(const node&)  = delete;
 public:
+    /**
+     * @brief Returns the category of this AST node.
+     * @see node_t
+     *
+     * @return The node category.
+     */
     virtual node_t category() const = 0;
 public:
+    /**
+     * @brief Compares two nodes for equality.
+     *
+     * Nodes are equal if they have the same category and
+     * their derived-class-specific contents are equal.
+     *
+     * @param rhs Node to compare against.
+     * @return true if the nodes are equal.
+     */
     bool operator==(const node& rhs) const { return category() == rhs.category() && equal(rhs); }
+
+    /**
+     * @brief Compares two nodes for inequality.
+     *
+     * @param rhs Node to compare against.
+     * @return true if the nodes are not equal.
+     */
     bool operator!=(const node& rhs) const { return !this->operator==(rhs); }
 public:
+    /**
+     * @brief Accepts a visitor.
+     *
+     * Dispatches to the visitor overload corresponding to the concrete node type.
+     *
+     * @param visitor Visitor instance.
+     */
     virtual void accept(visitor& visitor) const = 0;
 
+    /**
+     * @brief Prints a node to an output stream.
+     *
+     * @param os Output stream.
+     * @return The output stream.
+     */
     virtual std::ostream& print(std::ostream& os) const = 0;
 
+    /**
+     * @brief Prints a node to an output stream.
+     *
+     * Equivalent to calling node.print(os).
+     *
+     * @param os Output stream.
+     * @param node Node to print.
+     * @return The output stream.
+     */
     friend std::ostream& operator<<(std::ostream& os, const node& node) { return node.print(os); }
 protected:
+    /**
+     * @brief Compares two nodes for equality.
+     *
+     * @param rhs Node to compare against.
+     * @return true if nodes are equal.
+     */
     virtual bool equal(const node& rhs) const = 0;
 };
 

furc/include/furc/ast/program.hpp

@@ -9,14 +9,27 @@
 namespace furc {
 namespace ast {
 
+/**
+ * @brief Program AST node.
+ */
 class program_node final : public node {
 public:
     program_node() = default;
 
     node_t category() const override { return node_t::Program; }
 public:
+    /**
+     * @brief Adds a declaration to this program.
+     *
+     * @param declaration Declaration to add.
+     */
     void push(node_handle<declaration_node>&& declaration) { m_declarations.push_back(std::move(declaration)); }
 
+    /**
+     * @brief Returns a list of declarations of this program.
+     *
+     * @return The list of this program's declarations.
+     */
     const std::vector<node_handle<declaration_node>>& declarations() const { return m_declarations; }
 public:
     void accept(visitor& visitor) const override;

furc/include/furc/ast/statement.hpp

@@ -6,32 +6,66 @@
 namespace furc {
 namespace ast {
 
+/**
+ * @brief Statement node type.
+ */
 enum class statement_node_t {
-    Expression,
+    Expression,  /**< Expression */
-    Declaration,
+    Declaration, /**< Declaration */
-    Return,
+    Return,      /**< Return statement */
-    If,
+    If,          /**< If statement */
-    Compound,
+    Compound,    /**< Compound statement */
 };
 
+/**
+ * @brief Statement AST node.
+ */
 class statement_node : public node {
 public:
+    /**
+     * @brief Returns this node's category.
+     *
+     * @return node_t::Statement.
+     */
     node_t category() const override { return node_t::Statement; }
 
+    /**
+     * @brief Returns this node's statement type.
+     *
+     * @return The statement type.
+     */
     virtual statement_node_t statement_type() const = 0;
 protected:
     bool equal(const node& rhs) const override;
 };
 
+/**
+ * @brief Return statement AST node.
+ */
 class return_statement_node final : public statement_node {
 public:
     return_statement_node() = default;
 
+    /**
+     * @brief Construct a new return statement AST node.
+     *
+     * @param value Return value handle.
+     */
     return_statement_node(expression_node_h&& value)
       : m_value(std::move(value)) {}
 public:
+    /**
+     * @brief Returns this node's return value handle.
+     *
+     * @return The return value handle.
+     */
     expression_node_h value() const { return m_value; }
 public:
+    /**
+     * @brief Returns this node's statement type.
+     *
+     * @return statement_node_t::Return.
+     */
     statement_node_t statement_type() const override { return statement_node_t::Return; }
 public:
     void accept(visitor& visitor) const override;
@@ -40,21 +74,59 @@ public:
 protected:
     bool equal(const node& rhs) const override;
 private:
-    expression_node_h m_value;
+    expression_node_h m_value; /**< Return value handle. */
 };
 
+/**
+ * @brief If statement AST node.
+ */
 class if_statement_node final : public statement_node {
 public:
+    /**
+     * @brief Construct a new if statement AST node.
+     *
+     * @param cond Condition expression handle.
+     * @param then Then statement handle.
+     */
     if_statement_node(expression_node_h&& cond, statement_node_h&& then)
       : m_cond(std::move(cond)), m_then(std::move(then)) {}
 
+    /**
+     * @brief Construct a new if statement AST node.
+     *
+     * @param cond Condition expression handle.
+     * @param then Then statement handle.
+     * @param elze Else statement handle.
+     */
     if_statement_node(expression_node_h&& cond, statement_node_h&& then, statement_node_h&& elze)
       : m_cond(std::move(cond)), m_then(std::move(then)), m_else(std::move(elze)) {}
 public:
-    expression_node_h       cond() const { return m_cond; }
+    /**
+     * @brief Returns this node's condition expression handle.
+     *
+     * @return The condition expression handle.
+     */
+    expression_node_h cond() const { return m_cond; }
+
+    /**
+     * @brief Returns this node's then statement handle.
+     *
+     * @return The then statement handle.
+     */
     const statement_node_h& then() const { return m_then; }
+
+    /**
+     * @brief Returns this node's else statement handle.
+     *
+     * @return The else statement handle.
+     */
     const statement_node_h& elze() const { return m_else; }
 public:
+    /**
+     * @brief Returns this node's statement type.
+     *
+     * @return statement_node_t::If.
+     */
     statement_node_t statement_type() const override { return statement_node_t::If; }
 public:
     void accept(visitor& visitor) const override;
@@ -63,18 +135,36 @@ public:
 protected:
     bool equal(const node& rhs) const override;
 private:
-    expression_node_h m_cond;
+    expression_node_h m_cond; /**< The condition expression handle */
-    statement_node_h  m_then;
+    statement_node_h  m_then; /**< The then statement handle */
-    statement_node_h  m_else;
+    statement_node_h  m_else; /**< The else statement handle */
 };
 
+/**
+ * @brief Compound statement AST node.
+ */
 class compound_statement_node final : public statement_node {
 public:
+    /**
+     * @brief Construct a new compound statement AST node.
+     *
+     * @param body Body handle.
+     */
     compound_statement_node(body_h&& body)
       : m_body(std::move(body)) {}
 public:
+    /**
+     * @brief Returns this node's body handle.
+     *
+     * @return The body handle.
+     */
     const body_h& body() const { return m_body; }
 public:
+    /**
+     * @brief Returns this node's statement type.
+     *
+     * @return statement_node_t::Compound.
+     */
     statement_node_t statement_type() const override { return statement_node_t::Compound; }
 public:
     void accept(visitor& visitor) const override;
@@ -83,7 +173,7 @@ public:
 protected:
     bool equal(const node& rhs) const override;
 private:
-    body_h m_body;
+    body_h m_body; /**< The body handle. */
 };
 
 } // namespace ast

furc/include/furc/ast/visitor.hpp

@@ -6,28 +6,127 @@
 namespace furc {
 namespace ast {
 
+/**
+ * @brief Visitor pattern class for AST nodes.
+ */
 class visitor {
 public:
     visitor()          = default;
     virtual ~visitor() = default;
 
-    visitor(visitor&&)                 = default;
+    /**
-    visitor& operator=(visitor&&)      = default;
+     * @brief Move constructor.
-    visitor(const visitor&)            = default;
+     */
+    visitor(visitor&&) = default;
+
+    /**
+     * @brief Move constructor.
+     */
+    visitor& operator=(visitor&&) = default;
+
+    /**
+     * @brief Copy constructor.
+     */
+    visitor(const visitor&) = default;
+
+    /**
+     * @brief Copy constructor.
+     */
     visitor& operator=(const visitor&) = default;
 public:
-    virtual void visit(const string_literal_node&) {}
+    /**
-    virtual void visit(const integer_literal_node&) {}
+     * @brief Visit a string_literal_node.
-    virtual void visit(const var_read_expression_node&) {}
+     * @see string_literal_node
-    virtual void visit(const unaryop_expression_node&) {}
+     *
-    virtual void visit(const binop_expression_node&) {}
+     * @param node Node.
-    virtual void visit(const var_assign_expression_node&) {}
+     */
-    virtual void visit(const function_declaration_node&) {}
+    virtual void visit(const string_literal_node& node) {}
-    virtual void visit(const function_definition_node&) {}
-    virtual void visit(const return_statement_node&) {}
-    virtual void visit(const if_statement_node&) {}
-    virtual void visit(const compound_statement_node&) {}
 
+    /**
+     * @brief Visit a integer_literal_node.
+     * @see integer_literal_node
+     *
+     * @param node Node.
+     */
+    virtual void visit(const integer_literal_node& node) {}
+
+    /**
+     * @brief Visit a var_read_expression_node.
+     * @see var_read_expression_node
+     *
+     * @param node Node.
+     */
+    virtual void visit(const var_read_expression_node& node) {}
+
+    /**
+     * @brief Visit a unaryop_expression_node.
+     * @see unaryop_expression_node
+     *
+     * @param node Node.
+     */
+    virtual void visit(const unaryop_expression_node& node) {}
+
+    /**
+     * @brief Visit a binop_expression_node.
+     * @see binop_expression_node
+     *
+     * @param node Node.
+     */
+    virtual void visit(const binop_expression_node& node) {}
+
+    /**
+     * @brief Visit a var_assign_expression_node.
+     * @see var_assign_expression_node
+     *
+     * @param node Node.
+     */
+    virtual void visit(const var_assign_expression_node& node) {}
+
+    /**
+     * @brief Visit a function_declaration_node.
+     * @see function_declaration_node
+     *
+     * @param node Node.
+     */
+    virtual void visit(const function_declaration_node& node) {}
+
+    /**
+     * @brief Visit a function_definition_node.
+     * @see function_definition_node
+     *
+     * @param node Node.
+     */
+    virtual void visit(const function_definition_node& node) {}
+
+    /**
+     * @brief Visit a return_statement_node.
+     * @see return_statement_node
+     *
+     * @param node Node.
+     */
+    virtual void visit(const return_statement_node& node) {}
+
+    /**
+     * @brief Visit a if_statement_node.
+     * @see if_statement_node
+     *
+     * @param node Node.
+     */
+    virtual void visit(const if_statement_node& node) {}
+
+    /**
+     * @brief Visit a compound_statement_node.
+     * @see compound_statement_node
+     *
+     * @param node Node.
+     */
+    virtual void visit(const compound_statement_node& node) {}
+
+    /**
+     * @brief Visit a node handle with an error.
+     *
+     * @param handle Node handle.
+     */
     virtual void visit_error(const node_handle<node>& handle) {}
 };
 

furc/src/ast.cpp

@@ -143,11 +143,11 @@ void function_declaration_node::accept(visitor& visitor) const {
 }
 
 std::ostream& function_declaration_node::print(std::ostream& os) const {
-    return os << "function " << m_name->string << " declaration";
+    return os << "function " << p_name->string << " declaration";
 }
 
 bool function_declaration_node::equal(const node& rhs) const {
-    return declaration_node::equal(rhs) && m_name == reinterpret_cast<const function_declaration_node&>(rhs).m_name;
+    return declaration_node::equal(rhs) && p_name == reinterpret_cast<const function_declaration_node&>(rhs).p_name;
 }
 
 void function_definition_node::accept(visitor& visitor) const {
@@ -160,7 +160,7 @@ std::ostream& function_definition_node::print(std::ostream& os) const {
     if (m_body.present()) {
         for (const auto& entry : m_body->statements)
             os << '\n' << entry;
-        return os << '\n' << m_body->end << ": " << m_name->string << " end";
+        return os << '\n' << m_body->end << ": " << p_name->string << " end";
     }
     return os << m_body.error(); // error
 }

furc/test/parser.cpp

@@ -22,7 +22,7 @@ TEST(Parser, EmptyFunctions) {
     {
         auto first = program->declarations()[0];
         EXPECT_TRUE(first.present());
-        EXPECT_EQ(first->declaration_type(), declaration_node_t::FunctionDefinition);
+        EXPECT_EQ(first->declaration_type(), declaration_node_t::FuncDef);
         function_definition_node_h funcDef = first;
         EXPECT_EQ(funcDef->name()->string, "main");
         EXPECT_EQ(funcDef->body()->statements.size(), 0);
@@ -30,7 +30,7 @@ TEST(Parser, EmptyFunctions) {
     {
         auto second = program->declarations()[1];
         EXPECT_TRUE(second.present());
-        EXPECT_EQ(second->declaration_type(), declaration_node_t::FunctionDeclaration);
+        EXPECT_EQ(second->declaration_type(), declaration_node_t::Func);
         function_declaration_node_h funcDecl = second;
         EXPECT_EQ(funcDecl->name()->string, "foo");
     }
@@ -47,7 +47,7 @@ TEST(Parser, Literals) {
     {
         auto test1 = program->declarations()[0];
         EXPECT_TRUE(test1.present());
-        EXPECT_EQ(test1->declaration_type(), declaration_node_t::FunctionDefinition);
+        EXPECT_EQ(test1->declaration_type(), declaration_node_t::FuncDef);
         function_definition_node_h funcDef = test1;
         EXPECT_EQ(funcDef->name()->string, "test1");
         EXPECT_EQ(funcDef->body()->statements.size(), 1);
@@ -57,7 +57,7 @@ TEST(Parser, Literals) {
     {
         auto test2 = program->declarations()[1];
         EXPECT_TRUE(test2.present());
-        EXPECT_EQ(test2->declaration_type(), declaration_node_t::FunctionDefinition);
+        EXPECT_EQ(test2->declaration_type(), declaration_node_t::FuncDef);
         function_definition_node_h funcDecl = test2;
         EXPECT_EQ(funcDecl->name()->string, "test2");
     }
@@ -87,7 +87,7 @@ TEST(Parser, OperatorPrecedence_AddMul) {
     EXPECT_EQ(program->declarations().size(), 1);
     auto func = program->declarations()[0];
     EXPECT_TRUE(func.present());
-    EXPECT_EQ(func->declaration_type(), declaration_node_t::FunctionDefinition);
+    EXPECT_EQ(func->declaration_type(), declaration_node_t::FuncDef);
     function_definition_node_h funcDef = func;
     EXPECT_EQ(funcDef->name()->string, "main");
     EXPECT_EQ(funcDef->body()->statements.size(), 1);
@@ -115,7 +115,7 @@ TEST(Parser, OperatorPrecedence_Complex) {
     EXPECT_EQ(program->declarations().size(), 1);
     auto func = program->declarations()[0];
     EXPECT_TRUE(func.present());
-    EXPECT_EQ(func->declaration_type(), declaration_node_t::FunctionDefinition);
+    EXPECT_EQ(func->declaration_type(), declaration_node_t::FuncDef);
     function_definition_node_h funcDef = func;
     EXPECT_EQ(funcDef->name()->string, "main");
     EXPECT_EQ(funcDef->body()->statements.size(), 1);
@@ -153,7 +153,7 @@ TEST(Parser, UnaryOperator_Simple) {
     EXPECT_EQ(program->declarations().size(), 1);
     auto func = program->declarations()[0];
     EXPECT_TRUE(func.present());
-    EXPECT_EQ(func->declaration_type(), declaration_node_t::FunctionDefinition);
+    EXPECT_EQ(func->declaration_type(), declaration_node_t::FuncDef);
     function_definition_node_h funcDef = func;
     EXPECT_EQ(funcDef->name()->string, "main");
     EXPECT_EQ(funcDef->body()->statements.size(), 1);
@@ -175,7 +175,7 @@ TEST(Parser, UnaryOperator_PrePost) {
     EXPECT_EQ(program->declarations().size(), 1);
     auto func = program->declarations()[0];
     EXPECT_TRUE(func.present());
-    EXPECT_EQ(func->declaration_type(), declaration_node_t::FunctionDefinition);
+    EXPECT_EQ(func->declaration_type(), declaration_node_t::FuncDef);
     function_definition_node_h funcDef = func;
     EXPECT_EQ(funcDef->name()->string, "main");
     EXPECT_EQ(funcDef->body()->statements.size(), 1);
@@ -200,7 +200,7 @@ TEST(Parser, Paren) {
     EXPECT_EQ(program->declarations().size(), 1);
     auto func = program->declarations()[0];
     EXPECT_TRUE(func.present());
-    EXPECT_EQ(func->declaration_type(), declaration_node_t::FunctionDefinition);
+    EXPECT_EQ(func->declaration_type(), declaration_node_t::FuncDef);
     function_definition_node_h funcDef = func;
     EXPECT_EQ(funcDef->name()->string, "main");
     EXPECT_EQ(funcDef->body()->statements.size(), 1);
@@ -226,7 +226,7 @@ TEST(Parser, Assignment) {
     EXPECT_EQ(program->declarations().size(), 1);
     auto func = program->declarations()[0];
     EXPECT_TRUE(func.present());
-    EXPECT_EQ(func->declaration_type(), declaration_node_t::FunctionDefinition);
+    EXPECT_EQ(func->declaration_type(), declaration_node_t::FuncDef);
     function_definition_node_h funcDef = func;
     EXPECT_EQ(funcDef->name()->string, "main");
     EXPECT_EQ(funcDef->body()->statements.size(), 1);
@@ -255,7 +255,7 @@ TEST(Parser, CompoundAssignment) {
     EXPECT_EQ(program->declarations().size(), 1);
     auto func = program->declarations()[0];
     EXPECT_TRUE(func.present());
-    EXPECT_EQ(func->declaration_type(), declaration_node_t::FunctionDefinition);
+    EXPECT_EQ(func->declaration_type(), declaration_node_t::FuncDef);
     function_definition_node_h funcDef = func;
     EXPECT_EQ(funcDef->name()->string, "main");
     EXPECT_EQ(funcDef->body()->statements.size(), 1);