docs: Documented functions

pgtfs.cpp

@@ -2,6 +2,11 @@
 //
 // SPDX-License-Identifier: EUPL-1.2
 
+/**
+ * @file pgtfs.cpp
+ * @brief Implementation of PostgreSQL extension functions.
+ */
+
 extern "C"
 {
 #include <postgres.h>
@@ -19,6 +24,15 @@ extern "C"
     static const char *EXTENSION_VERSION = "0.0.1";
 
     PG_FUNCTION_INFO_V1(pgtfs_csa);
+    /**
+     * @brief Implements the pgtfs_csa PostgreSQL extension function.
+     * 
+     * This function performs the Connection Scan Algorithm (CSA) to find connections
+     * between the specified origin and destination at the given departure time.
+     * 
+     * @param fcinfo Function call information.
+     * @return A set of rows representing the solutions found.
+     */
     Datum pgtfs_csa(PG_FUNCTION_ARGS)
     {
         FuncCallContext *funcctx;
@@ -117,6 +131,15 @@ extern "C"
     }
 
     PG_FUNCTION_INFO_V1(pgtfs_version);
+    /**
+     * @brief Returns version information about the extension.
+     * 
+     * This function returns a textual representation of version information
+     * including the extension version, PostgreSQL version, and compiler version.
+     * 
+     * @param fcinfo Function call information.
+     * @return A text representation of the version information.
+     */
     Datum pgtfs_version(PG_FUNCTION_ARGS)
     {
         const char *COMPILER_VERSION = __VERSION__;

src/csa/csa.h

@@ -2,6 +2,11 @@
 //
 // SPDX-License-Identifier: EUPL-1.2
 
+/**
+ * @file csa.h
+ * @brief Declarations for the CSA (Connection Scan Algorithm) module.
+ */
+
 #ifndef CSA_H
 #define CSA_H
 
@@ -11,14 +16,31 @@
 #include "postgres.h"
 #include "src/models/network.h"
 
+/**
+ * @struct SolutionCSA
+ * @brief Structure representing a solution in the Connection Scan Algorithm.
+ */
 struct SolutionCSA
 {
-    std::string stop_id;
-    int stop_sequence;
-    time_t arrival_time;
-    std::string trip_id;
+    std::string stop_id; /**< Stop ID */
+    int stop_sequence; /**< Stop sequence */
+    time_t arrival_time; /**< Arrival time */
+    std::string trip_id; /**< Trip ID */
 };
 
+/**
+ * @brief Performs the Connection Scan Algorithm.
+ * 
+ * This function performs the Connection Scan Algorithm (CSA) to find connections
+ * between the specified origin and destination at the given departure time.
+ * 
+ * @param origin The origin stop ID.
+ * @param destination The destination stop ID.
+ * @param departure_time The departure time.
+ * @param network Pointer to the network of stops.
+ * @param network_size The size of the network.
+ * @return A vector of SolutionCSA structures representing the solutions found.
+ */
 std::vector<SolutionCSA> perform_CSA(const char *origin, const char *destination, float8 departure_time, NetworkRow *network, int64_t network_size);
 
 #endif /* CSA_H */

src/models/network.h

@@ -2,6 +2,12 @@
 //
 // SPDX-License-Identifier: EUPL-1.2
 
+/**
+ * @file network.h
+ * @brief Declarations for functions related to network operations.
+ */
+
+
 #ifndef NETWORK_H
 #define NETWORK_H
 
@@ -16,17 +22,39 @@
 
 #define MAX_STRING_LENGTH 256
 
+/**
+ * @struct NetworkRow
+ * @brief Structure representing a row in a network.
+ */
 typedef struct {
-    char trip_id[MAX_STRING_LENGTH];
-    char from_stop_id[MAX_STRING_LENGTH];
-    char to_stop_id[MAX_STRING_LENGTH];
-    float8 arrival_time;
-    float8 departure_time;
-    float8 travel_time;
-    bool nulls[6]; 
+    char trip_id[MAX_STRING_LENGTH];  /**< Trip ID */
+    char from_stop_id[MAX_STRING_LENGTH]; /**< From stop ID */
+    char to_stop_id[MAX_STRING_LENGTH]; /**< To stop ID */
+    float8 arrival_time; /**< Arrival time as epoch*/
+    float8 departure_time; /**< Departure time as epoch*/
+    float8 travel_time; /**< Travel time */
+    bool nulls[6];  /**< Array of boolean flags indicating null values */
 } NetworkRow;
 
+/**
+ * @brief Creates a network from the given query string.
+ * 
+ * This function creates a network based on the provided query string
+ * and returns a pointer to the network.
+ * 
+ * @param network_query_str The query string specifying the network.
+ * @param network_size Pointer to store the size of the network.
+ * @return Pointer to the created network.
+ */
 NetworkRow *create_network(const char *network_query_str, int64_t *network_size);
 
+/**
+ * @brief Prints the network rows.
+ * 
+ * This function prints the given network rows along with their details.
+ * 
+ * @param network_rows Pointer to the network rows array.
+ * @param network_size The size of the network.
+ */
 void print_network_rows(NetworkRow* network_rows, int64_t network_size);
 #endif /* NETWORK_H */