Added documentation

Author: LukasMolzberger

include/fields/abstract_function_definition.h

@@ -1,3 +1,12 @@
+/**
+ * @file abstract_function_definition.h
+ * @brief Defines the AbstractFunctionDefinition class, which represents mathematical functions in the field graph.
+ * 
+ * The AbstractFunctionDefinition class provides a base for mathematical functions
+ * that operate on a fixed number of inputs in the field graph. It handles the
+ * computation and propagation of updates based on input changes.
+ */
+
 #ifndef ABSTRACT_FUNCTION_DEFINITION_H
 #define ABSTRACT_FUNCTION_DEFINITION_H
 
@@ -6,18 +15,50 @@
 #include "fields/obj.h"
 #include "fields/field.h"
 
+/**
+ * @class AbstractFunctionDefinition
+ * @brief Base class for mathematical functions with fixed arguments.
+ * 
+ * The AbstractFunctionDefinition class extends FieldDefinition to provide:
+ * - Fixed number of input arguments
+ * - Abstract computation interface
+ * - Update propagation logic
+ * 
+ * This class serves as the foundation for specific mathematical operations
+ * like addition, multiplication, or exponential functions in the field graph.
+ */
 class AbstractFunctionDefinition : public FieldDefinition {
+
 public:
     // Constructors
     AbstractFunctionDefinition(Type* objectType, const std::string& name, int numArgs, double tolerance);
 
     // Destructor
     virtual ~AbstractFunctionDefinition() = default;
 
-    // Abstract method
+
+    /**
+     * @brief Computes the update value based on input changes
+     * 
+     * This pure virtual method must be implemented by concrete function classes
+     * to define their specific mathematical operation.
+     * 
+     * @param inputs Array of input values
+     * @param updates Array of input updates
+     * @param numInputs Number of inputs (must match constructor value)
+     * @return The computed update value
+     */
     virtual double computeUpdate(Obj* obj, FieldLinkDefinition* fl, double u) = 0;
 
-    // Overridden method
+    /**
+     * @brief Transmits an update to connected fields
+     * 
+     * Propagates the computed update through the field graph,
+     * respecting tolerance thresholds and update rules.
+     * 
+     * @param field The field being updated
+     * @param update The update value to transmit
+     */
     void transmit(Field* targetField, FieldLinkDefinition* fl, double u) override;
 };
 

include/fields/direction.h

@@ -1,3 +1,11 @@
+/**
+ * @file direction.h
+ * @brief Defines the Direction interface and its implementations for field connections.
+ * 
+ * The Direction interface and its implementations (Input and Output) provide
+ * directionality for field connections in the field graph, enabling proper
+ * update propagation and graph traversal.
+ */
 
 #ifndef DIRECTION_H
 #define DIRECTION_H
@@ -11,24 +19,83 @@ class FieldLinkDefinition;
 class FlattenedType;
 class Type;
 
+class Field;
+class FieldLinkDefinition;
 
+/**
+ * @class Direction
+ * @brief Interface for field connection directionality.
+ * 
+ * The Direction interface defines the contract for handling directionality
+ * in field connections. It provides:
+ * - Direction identification
+ * - Link traversal
+ * - Update transmission
+ * - Direction inversion
+ * 
+ * This abstraction enables flexible and extensible field graph structures
+ * with proper update propagation.
+ */
 class Direction {
 public:
-    static Direction* INPUT;
-    static Direction* OUTPUT;
+    static Direction* INPUT;  ///< Singleton instance for input direction
+    static Direction* OUTPUT; ///< Singleton instance for output direction
+
+    virtual ~Direction() = default;
 
+    /**
+     * @brief Gets the direction identifier
+     * 
+     * @return The direction ID
+     */
     virtual int getDirectionId() const = 0;
+
+    /**
+     * @brief Gets the inverse direction
+     * 
+     * @return The opposite direction
+     */
     virtual Direction* invert() const = 0;
+
+    /**
+     * @brief Gets the link definition for a field
+     * 
+     * @param field The field to get the link for
+     * @return The link definition
+     */
     virtual std::vector<FieldLinkDefinition*> getFieldLinkDefinitions(FieldDefinition* fd) const = 0;
+    
+    /**
+     * @brief Gets the flattened type for a given type in this direction
+     * 
+     * Retrieves the flattened type representation associated with the given type
+     * in the current direction (input or output). Flattened types are used to
+     * optimize type hierarchy traversal during runtime.
+     *
+     * @param type The type to get the flattened representation for
+     * @return The flattened type representation
+     */
     virtual FlattenedType* getFlattenedType(Type* type) const = 0;
+
+    /**
+     * @brief Transmits an update through the connection
+     * 
+     * @param field The field being updated
+     * @param link The link definition
+     * @param update The update value
+     */
     virtual void transmit(Field* originField,
                           FieldLinkDefinition* fl,
                           Obj* relatedObject) const = 0;
-
-    virtual ~Direction() = default; // Ensure proper cleanup for derived classes
 };
 
-
+/**
+ * @class Input
+ * @brief Represents an input direction in field connections.
+ * 
+ * The Input class implements the Direction interface for input connections,
+ * handling update reception and propagation from source to target fields.
+ */
 class Input : public Direction {
 public:
     int getDirectionId() const override;
@@ -40,7 +107,13 @@ class Input : public Direction {
                   Obj* relatedObject) const override;
 };
 
-
+/**
+ * @class Output
+ * @brief Represents an output direction in field connections.
+ * 
+ * The Output class implements the Direction interface for output connections,
+ * handling update propagation from target to source fields.
+ */
 class Output : public Direction {
 public:
     int getDirectionId() const override;
@@ -52,5 +125,4 @@ class Output : public Direction {
                   Obj* relatedObject) const override;
 };
 
-
-#endif //DIRECTION_H
+#endif // DIRECTION_H

include/fields/field.h

@@ -1,3 +1,12 @@
+/**
+ * @file field.h
+ * @brief Defines the Field class, which represents runtime instances of field definitions.
+ * 
+ * The Field class is the runtime representation of a field definition in the field graph.
+ * It manages the current and updated values of a field, handles update propagation,
+ * and integrates with the event queue system for asynchronous processing.
+ */
+
 #ifndef FIELD_H
 #define FIELD_H
 
@@ -12,47 +21,190 @@ class Queue;
 class ProcessingPhase;
 
 
+/**
+ * @class Field
+ * @brief Runtime instance of a field definition in the field graph.
+ * 
+ * Fields are the computational units that perform actual calculations in the field graph.
+ * Each field:
+ * - Maintains current and updated values
+ * - Propagates updates to connected fields
+ * - Integrates with the event queue for asynchronous processing
+ * - Associates with an object in the object graph
+ * 
+ * The field graph's event-driven nature is implemented through the QueueInterceptor,
+ * which manages when and how updates are processed.
+ */
 class Field {
 private:
-    FieldDefinition* fieldDefinition;
-    int id;
-    Obj* object;
-    double value;
-    double updatedValue;
-    bool withinUpdate;
-    QueueInterceptor* interceptor;
+    FieldDefinition* fieldDefinition;  ///< The field definition this field is an instance of
+    int id;                           ///< Unique identifier for this field
+    Obj* object;                      ///< The object this field is associated with
+    double value;                     ///< Current value of the field
+    double updatedValue;              ///< Updated value during processing
+    bool withinUpdate;                ///< Flag indicating if field is being updated
+    QueueInterceptor* interceptor;    ///< Manages event queue integration
 
 public:
+    /**
+     * @brief Constructs a new Field
+     * 
+     * @param obj The object this field is associated with
+     * @param fd The field definition this field is an instance of
+     * @param id The unique identifier for this field
+     */
     Field(Obj* obj, FieldDefinition* fd, int id);
 
+    /**
+     * @brief Gets the field's unique identifier
+     * 
+     * @return The field ID
+     */
     int getId() const;
+
+    /**
+     * @brief Checks if the field is currently being updated
+     * 
+     * @return true if the field is within an update operation
+     */
     bool isWithinUpdate();
+
+    /**
+     * @brief Gets the current value of the field
+     * 
+     * @return The current value
+     */
     double getValue();
+
+    /**
+     * @brief Gets the updated value of the field
+     * 
+     * @return The updated value
+     */
     double getUpdatedValue();
+
+    /**
+     * @brief Gets the object this field is associated with
+     * 
+     * @return The associated object
+     */
     Obj* getObject();
 
+    /**
+     * @brief Sets the field to be queued for processing
+     * 
+     * @param q The queue to use
+     * @param phase The processing phase
+     * @param isNextRound Whether to process in the next round
+     * @return This field for method chaining
+     */
     Field& setQueued(Queue* q, ProcessingPhase& phase, bool isNextRound);
 
+    /**
+     * @brief Gets the field definition this field is an instance of
+     * 
+     * @return The field definition
+     */
     FieldDefinition* getFieldDefinition();
 
+    /**
+     * @brief Gets the tolerance threshold for this field
+     * 
+     * @return The tolerance threshold
+     */
     double getTolerance() const;
+
+    /**
+     * @brief Gets the name of this field
+     * 
+     * @return The field name
+     */
     std::string getName() const;
 
+    /**
+     * @brief Gets the queue interceptor for this field
+     * 
+     * @return The queue interceptor
+     */
     QueueInterceptor* getInterceptor();
+
+    /**
+     * @brief Sets the queue interceptor for this field
+     * 
+     * @param interceptor The queue interceptor to set
+     */
     void setInterceptor(QueueInterceptor* interceptor);
 
+    /**
+     * @brief Sets the current value of the field
+     * 
+     * @param v The value to set
+     */
     void setValue(double v);
+
+    /**
+     * @brief Triggers an update to the field's value
+     * 
+     * @param u The update value
+     */
     void triggerUpdate(double u);
+
+    /**
+     * @brief Gets the current update value
+     * 
+     * @return The update value
+     */
     double getUpdate() const;
+
+    /**
+     * @brief Propagates the current update to connected fields
+     */
     void propagateUpdate();
 
+    /**
+     * @brief Receives an update from another field
+     * 
+     * @param u The update value
+     */
     void receiveUpdate(double u);
 
+    /**
+     * @brief Converts the field to a string representation
+     * 
+     * @return String representation
+     */
     std::string toString() const;
+
+    /**
+     * @brief Gets a string representation of the field's value
+     * 
+     * @return Value string representation
+     */
     std::string getValueString() const;
 
+    /**
+     * @brief Checks if a field's value is considered true
+     * 
+     * @param f The field to check
+     * @return true if the field's value is considered true
+     */
     static bool isTrue(Field* f);
+
+    /**
+     * @brief Checks if a field's value is considered true
+     * 
+     * @param f The field to check
+     * @param updatedValue Whether to use the updated value
+     * @return true if the field's value is considered true
+     */
     static bool isTrue(Field* f, bool updatedValue);
+
+    /**
+     * @brief Checks if a value is considered true
+     * 
+     * @param v The value to check
+     * @return true if the value is considered true
+     */
     static bool isTrue(double v);
 };