[agroal#470] API documentation

fluca1978 · Sep 21, 2024 · bf4a9a3 · bf4a9a3
1 parent af9a90c
commit bf4a9a3
Show file tree

Hide file tree

Showing 9 changed files with 95 additions and 50 deletions.
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -105,6 +105,13 @@ else ()
   message(STATUS "pdflatex needed. The generation process will be skipped.")
 endif()
 
+find_package(Doxygen
+             REQUIRED dot)
+
+if (DOXYGEN_FOUND)
+  message(status "Doxygen found: ${DOXYGEN_EXECUTABLE}")
+endif()
+
 if (${CMAKE_SYSTEM_NAME} STREQUAL "Linux")
   find_package(Libatomic)
   if (LIBATOMIC_FOUND)

diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
@@ -139,3 +139,31 @@ if(generation)
   install(FILES ${MANUAL_OUTPUT_DIR}/pgagroal-dev-guide.html DESTINATION share/doc/pgagroal/manual)
 
 endif()
+
+#
+# Generate API docs
+#
+if (DOXYGEN_FOUND)
+  add_custom_target(api ALL)
+
+  set(DOXYGEN_GENERATE_HTML YES)
+  set(DOXYGEN_GENERATE_MAN NO)
+  set(DOXYGEN_WARN_AS_ERROR FAIL_ON_WARNINGS)
+  set(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile.doxygen)
+
+  doxygen_add_docs(doxygen ${PROJECT_SOURCE_DIR}/src/include/)
+
+  if (${DOXYGEN_VERSION} STREQUAL "1.10.0" OR ${DOXYGEN_VERSION} STREQUAL "1.11.0" OR ${DOXYGEN_VERSION} STREQUAL "1.12.0")
+    add_custom_command(
+      TARGET api
+      COMMAND ${DOXYGEN_EXECUTABLE} -q ${DOXYFILE_OUT}
+      COMMENT "Generating API documentation"
+    )
+  else()
+    add_custom_command(
+      TARGET api
+      COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT}
+      COMMENT "Generating API documentation"
+    )
+  endif()
+endif()
diff --git a/doc/DEVELOPERS.md b/doc/DEVELOPERS.md
@@ -51,6 +51,16 @@ This process is optional. If you choose not to generate the PDF and HTML files,
     dnf install 'tex(footnote.sty)' 'tex(footnotebackref.sty)' 'tex(pagecolor.sty)' 'tex(hardwrap.sty)' 'tex(mdframed.sty)' 'tex(sourcesanspro.sty)' 'tex(ly1enc.def)' 'tex(sourcecodepro.sty)' 'tex(titling.sty)' 'tex(csquotes.sty)' 'tex(zref-abspage.sty)' 'tex(needspace.sty)'
     ```
 
+#### Generate API guide
+
+This process is optional. If you choose not to generate the API HTML files, you can opt out of downloading these dependencies, and the process will automatically skip the generation.
+
+Download dependencies
+
+    ``` sh
+    dnf install graphviz doxygen
+    ```
+
 ### Build
 
 ``` sh

diff --git a/src/include/management.h b/src/include/management.h
@@ -83,16 +83,16 @@ extern "C" {
 #define PGAGROAL_EXECUTABLE_CLI 2
 #define PGAGROAL_EXECUTABLE_VAULT 3
 
-/*
+/** @struct pgagroal_version_info
  * stores the application name and its version
  * which are sent through the socket
  */
 struct pgagroal_version_info
 {
-   char s[2];
-   int command;
-   char v[3];
-   int version;
+   char s[2];   /**< The command encoded */
+   int command; /**< The command */
+   char v[3];   /**< The version encoded */
+   int version; /**< The version */
 };
 
 /**

diff --git a/src/include/message.h b/src/include/message.h
@@ -44,7 +44,7 @@ extern "C" {
 #define MESSAGE_STATUS_OK    1
 #define MESSAGE_STATUS_ERROR 2
 
-/** @struct
+/** @struct message
  * Defines a message
  */
 struct message

diff --git a/src/include/pgagroal.h b/src/include/pgagroal.h
@@ -257,7 +257,7 @@ extern void* prometheus_shmem;
  */
 extern void* prometheus_cache_shmem;
 
-/** @struct
+/** @struct server
  * Defines a server
  */
 struct server
@@ -273,7 +273,7 @@ struct server
    int lineno;                      /**< The line number within the configuration file */
 } __attribute__ ((aligned (64)));
 
-/** @struct
+/** @struct connection
  * Defines a connection
  */
 struct connection
@@ -300,7 +300,7 @@ struct connection
    int fd;                 /**< The descriptor */
 } __attribute__ ((aligned (64)));
 
-/** @struct
+/** @struct hba
  * Defines a HBA entry
  */
 struct hba
@@ -313,7 +313,7 @@ struct hba
    int lineno;                        /**< The line number within the configuration file */
 } __attribute__ ((aligned (64)));
 
-/** @struct
+/** @struct limit
  * Defines a limit entry
  */
 struct limit
@@ -327,7 +327,7 @@ struct limit
    int lineno;                         /**< The line number within the configuration file */
 } __attribute__ ((aligned (64)));
 
-/** @struct
+/** @struct user
  * Defines a user
  */
 struct user
@@ -336,24 +336,24 @@ struct user
    char password[MAX_PASSWORD_LENGTH]; /**< The password */
 } __attribute__ ((aligned (64)));
 
-/** @struct
+/** @struct vault_server
  * Defines a vault server
  */
 struct vault_server
 {
-   struct server server;
-   struct user user;
+   struct server server; /**< The server */
+   struct user user;     /**< The user */
 } __attribute__ ((aligned (64)));
 
-/** @struct
+/** @struct prometheus_connection
  * Defines the Prometheus connection metric
  */
 struct prometheus_connection
 {
    atomic_ullong query_count;           /**< The number of queries per connection */
 } __attribute__ ((aligned (64)));
 
-/**
+/** @struct prometheus_cache
  * A structure to handle the Prometheus response
  * so that it is possible to serve the very same
  * response over and over depending on the cache
@@ -375,7 +375,7 @@ struct prometheus_cache
    char data[];          /**< the payload */
 } __attribute__ ((aligned (64)));
 
-/** @struct
+/** @struct prometheus
  * Defines the common Prometheus metrics
  */
 struct prometheus
@@ -392,7 +392,7 @@ struct prometheus
 
 } __attribute__ ((aligned (64)));
 
-/** @struct
+/** @struct main_prometheus
  * Defines the Main Prometheus metrics
  */
 struct main_prometheus
@@ -414,8 +414,8 @@ struct main_prometheus
    atomic_ulong connection_success;            /**< The number of success calls */
 
    /**< The number of connection awaiting due to `blocking_timeout` */
-   atomic_ulong connections_awaiting[NUMBER_OF_LIMITS];
-   atomic_ulong connections_awaiting_total;
+   atomic_ulong connections_awaiting[NUMBER_OF_LIMITS]; /**< The number of connection waiting per limit */
+   atomic_ulong connections_awaiting_total;             /**< The number of connection waiting in total */
 
    atomic_ulong auth_user_success;      /**< The number of AUTH_SUCCESS calls */
    atomic_ulong auth_user_bad_password; /**< The number of AUTH_BAD_PASSWORD calls */
@@ -437,15 +437,15 @@ struct main_prometheus
 
 } __attribute__ ((aligned (64)));
 
-/** @struct
+/** @struct vault_prometheus
  * Defines the Vault Prometheus metrics
  */
 struct vault_prometheus
 {
-   struct prometheus prometheus_base;
+   struct prometheus prometheus_base; /**< The Prometheus base */
 } __attribute__ ((aligned (64)));
 
-/** @struct
+/** @struct configuration
  * Defines the common configurations between pgagroal and vault
  */
 struct configuration
@@ -480,7 +480,7 @@ struct configuration
    unsigned int metrics_cache_max_size; /**< Number of bytes max to cache the Prometheus response */
 };
 
-/** @struct
+/** @struct vault_configuration
  * Defines the configuration of pgagroal-vault
  */
 struct vault_configuration
@@ -491,7 +491,7 @@ struct vault_configuration
    struct vault_server vault_server; /**< The vault servers */
 } __attribute__ ((aligned (64)));
 
-/** @struct
+/** @struct main_configuration
  * Defines the configuration and state of pgagroal
  */
 struct main_configuration

diff --git a/src/include/pipeline.h b/src/include/pipeline.h
@@ -50,7 +50,7 @@ typedef void (* stop)(struct ev_loop*, struct worker_io*);
 typedef void (* destroy)(void*, size_t);
 typedef void (* periodic)(void);
 
-/** @struct
+/** @struct pipeline
  * Define the structure for a pipeline
  */
 struct pipeline

diff --git a/src/include/utils.h b/src/include/utils.h
@@ -38,7 +38,7 @@ extern "C" {
 
 #include <stdlib.h>
 
-/** @struct
+/** @struct signal_info
  * Defines the signal structure
  */
 struct signal_info
@@ -47,26 +47,26 @@ struct signal_info
    int slot;                /**< The slot */
 };
 
-/** @struct
+/** @struct accept_io
  * Defines the accept io structure
  */
 struct accept_io
 {
-   struct ev_io io;
-   int socket;
-   char** argv;
+   struct ev_io io; /**< The I/O */
+   int socket;      /**< The socket */
+   char** argv;     /**< The argv */
 };
 
-/** @struct
+/** @struct client
  * Defines the client structure
  */
 struct client
 {
-   pid_t pid;
-   struct client* next;
+   pid_t pid;           /**< The process id */
+   struct client* next; /**< The next client */
 };
 
-/** @struct
+/** @struct pgagroal_command
  * Defines pgagroal commands.
  * The necessary fields are marked with an ">".
  *
@@ -89,23 +89,23 @@ struct client
  */
 struct pgagroal_command
 {
-   const char* command;
-   const char* subcommand;
-   const int accepted_argument_count[MISC_LENGTH];
+   const char* command;                            /**< The command */
+   const char* subcommand;                         /**< The sub-command */
+   const int accepted_argument_count[MISC_LENGTH]; /**< The array of accepted arguments */
 
-   const int action;
-   const int mode;
-   const char* default_argument;
-   const char* log_message;
+   const int action;                               /**< The action */
+   const int mode;                                 /**< The mode of the action */
+   const char* default_argument;                   /**< The default argument */
+   const char* log_message;                        /**< The log message */
 
    /* Deprecation information */
-   bool deprecated;
-   unsigned int deprecated_since_major;
-   unsigned int deprecated_since_minor;
-   const char* deprecated_by;
+   bool deprecated;                                /**< Is the command deprecated */
+   unsigned int deprecated_since_major;            /**< Deprecated since major */
+   unsigned int deprecated_since_minor;            /**< Deprecated since minor */
+   const char* deprecated_by;                      /**< Deprecated by */
 };
 
-/** @struct
+/** @struct pgagroal_parsed_command
  * Holds parsed command data.
  *
  * Fields:
@@ -114,8 +114,8 @@ struct pgagroal_command
  */
 struct pgagroal_parsed_command
 {
-   const struct pgagroal_command* cmd;
-   char* args[MISC_LENGTH];
+   const struct pgagroal_command* cmd; /**< The command */
+   char* args[MISC_LENGTH];            /**< The command arguments */
 };
 
 /**

diff --git a/src/include/worker.h b/src/include/worker.h
@@ -46,7 +46,7 @@ extern "C" {
 #define WORKER_SERVER_FATAL   5
 #define WORKER_FAILOVER       6
 
-/** @struct
+/** @struct worker_io
  * The worker structure for each IO event
  */
 struct worker_io