Initial source documentation

src/include/configuration.h

@@ -36,19 +36,28 @@ extern "C" {
 #include <stdlib.h>
 
 /**
- *
+ * Initialize the configuration structure
+ * @param shmem The shared memory segment
+ * @param size The size of the configuration
+ * @return 0 upon success, otherwise 1
  */
 int
 pgagroal_init_configuration(void* shmem, size_t size);
 
 /**
- *
+ * Read the configuration from a file
+ * @param filename The file name
+ * @param shmem The shared memory segment
+ * @return 0 upon success, otherwise 1
  */
 int
 pgagroal_read_configuration(char* filename, void* shmem);
 
 /**
- *
+ * Read the HBA configuration from a file
+ * @param filename The file name
+ * @param shmem The shared memory segment
+ * @return 0 upon success, otherwise 1
  */
 int
 pgagroal_read_hba_configuration(char* filename, void* shmem);

src/include/logging.h

@@ -50,13 +50,17 @@ extern "C" {
 #define PGAGROAL_LOGGING_LEVEL_FATAL   6
 
 /**
- *
+ * Start the logging system
+ * @param shmem The shared memory segment
+ * @return 0 upon success, otherwise 1
  */
 int
 pgagroal_start_logging(void* shmem);
 
 /**
- *
+ * Stop the logging system
+ * @param shmem The shared memory segment
+ * @return 0 upon success, otherwise 1
  */
 int
 pgagroal_stop_logging(void* shmem);

src/include/management.h

@@ -42,37 +42,55 @@ extern "C" {
 #define MANAGEMENT_FLUSH               3
 
 /**
- *
+ * Read the management header
+ * @param socket The socket descriptor
+ * @param id The resulting management identifier
+ * @param slot The resulting slot
+ * @return 0 upon success, otherwise 1
  */
 int
 pgagroal_management_read_header(int socket, signed char* id, int32_t* slot);
 
 /**
- *
+ * Read the management payload
+ * @param socket The socket descriptor
+ * @param id The management identifier
+ * @param payload The resulting payload
+ * @return 0 upon success, otherwise 1
  */
 int
 pgagroal_management_read_payload(int socket, signed char id, int* payload);
 
 /**
- *
+ * Free the management payload
+ * @param payload The payload
  */
 void
 pgagroal_management_free_payload(void* payload);
 
 /**
- *
+ * Management operation: Transfer a connection
+ * @param shmem The shared memory segment
+ * @param slot The slot
+ * @return 0 upon success, otherwise 1
  */
 int
 pgagroal_management_transfer_connection(void* shmem, int32_t slot);
 
 /**
- *
+ * Management operation: Kill a connection
+ * @param shmem The shared memory segment
+ * @param slot The slot
+ * @return 0 upon success, otherwise 1
  */
 int
 pgagroal_management_kill_connection(void* shmem, int32_t slot);
 
 /**
- *
+ * Management operation: Flush the pool
+ * @param shmem The shared memory segment
+ * @param mode The flush mode
+ * @return 0 upon success, otherwise 1
  */
 int
 pgagroal_management_flush(void* shmem, int32_t mode);

src/include/memory.h

@@ -38,31 +38,34 @@ extern "C" {
 #include <stdlib.h>
 
 /**
- *
+ * Initialize a memory segment for the process local message structure
+ * @param shmem The shared memory segment
  */
 void
 pgagroal_memory_init(void* shmem);
 
 /**
- *
+ * Get the message structure
+ * @return The structure
  */
 struct message*
 pgagroal_memory_message(void);
 
 /**
- *
+ * Get the pointer to the message data section
+ * @return The pointer
  */
 void*
 pgagroal_memory_data(void);
 
 /**
- *
+ * Free the memory segment
  */
 void
 pgagroal_memory_free(void);
 
 /**
- *
+ * Destroy the memory segment
  */
 void
 pgagroal_memory_destroy(void);

src/include/message.h

@@ -43,115 +43,164 @@ extern "C" {
 #define MESSAGE_STATUS_ERROR 2
 
 /**
- *
+ * Read a message
+ * @param socket The socket descriptor
+ * @param msg The resulting message
+ * @return One of MESSAGE_STATUS_ZERO, MESSAGE_STATUS_OK or MESSAGE_STATUS_ERROR
  */
 int
 pgagroal_read_message(int socket, struct message** msg);
 
 /**
- *
+ * Read a message in blocking mode
+ * @param socket The socket descriptor
+ * @param msg The resulting message
+ * @return One of MESSAGE_STATUS_ZERO, MESSAGE_STATUS_OK or MESSAGE_STATUS_ERROR
  */
 int
 pgagroal_read_block_message(int socket, struct message** msg);
 
 /**
- *
+ * Write a message
+ * @param socket The socket descriptor
+ * @param msg The message
+ * @return One of MESSAGE_STATUS_ZERO, MESSAGE_STATUS_OK or MESSAGE_STATUS_ERROR
  */
 int
 pgagroal_write_message(int socket, struct message* msg);
 
 /**
- *
+ * Write a message with NODELAY
+ * @param socket The socket descriptor
+ * @param msg The message
+ * @return One of MESSAGE_STATUS_ZERO, MESSAGE_STATUS_OK or MESSAGE_STATUS_ERROR
  */
 int
 pgagroal_write_nodelay_message(int socket, struct message* msg);
 
 /**
- *
+ * Create a message
+ * @param data A pointer to the data
+ * @param length The length of the message
+ * @param msg The resulting message
+ * @return 0 upon success, otherwise 1
  */
 int
 pgagroal_create_message(void* data, ssize_t length, struct message** msg);
 
 /**
- *
+ * Copy a message
+ * @param msg The resulting message
+ * @return The copy
  */
 struct message*
 pgagroal_copy_message(struct message* msg);
 
 /**
- *
+ * Free a message
+ * @param msg The resulting message
  */
 void
 pgagroal_free_message(struct message* msg);
 
 /**
- *
+ * Free a copy message
+ * @param msg The resulting message
  */
 void
 pgagroal_free_copy_message(struct message* msg);
 
 /**
- *
+ * Get the request identifier
+ * @param msg The message
+ * @return The identifier
  */
 int32_t
 pgagroal_get_request(struct message* msg);
 
 /**
- *
+ * Extract the user name and database from a message
+ * @param msg The message
+ * @param username The resulting user name
+ * @param database The resulting database
+ * @return 0 upon success, otherwise 1
  */
 int
 pgagroal_extract_username_database(struct message* msg, char** username, char** database);
 
 /**
- *
+ * Write an empty message
+ * @param socket The socket descriptor
+ * @return 0 upon success, otherwise 1
  */
 int
 pgagroal_write_empty(int socket);
 
 /**
- *
+ * Write a notice message
+ * @param socket The socket descriptor
+ * @return 0 upon success, otherwise 1
  */
 int
 pgagroal_write_notice(int socket);
 
 /**
- *
+ * Write a pool is full message
+ * @param socket The socket descriptor
+ * @return 0 upon success, otherwise 1
  */
 int
 pgagroal_write_pool_full(int socket);
 
 /**
- *
+ * Write a bad password message
+ * @param socket The socket descriptor
+ * @param username The user name
+ * @return 0 upon success, otherwise 1
  */
 int
 pgagroal_write_bad_password(int socket, char* username);
 
 /**
- *
+ * Write an unsupported security model message
+ * @param socket The socket descriptor
+ * @param username The user name
+ * @return 0 upon success, otherwise 1
  */
 int
 pgagroal_write_unsupported_security_model(int socket, char* username);
 
 /**
- *
+ * Write a no HBA entry message
+ * @param socket The socket descriptor
+ * @param username The user name
+ * @param database The database
+ * @param address The client address
+ * @return 0 upon success, otherwise 1
  */
 int
 pgagroal_write_no_hba_entry(int socket, char* username, char* database, char* address);
 
 /**
- *
+ * Write a deallocate all message
+ * @param socket The socket descriptor
+ * @return 0 upon success, otherwise 1
  */
 int
 pgagroal_write_deallocate_all(int socket);
 
 /**
- *
+ * Write a terminate message
+ * @param socket The socket descriptor
+ * @return 0 upon success, otherwise 1
  */
 int
 pgagroal_write_terminate(int socket);
 
 /**
- *
+ * Is the connection valid
+ * @param socket The socket descriptor
+ * @return true upon success, otherwise false
  */
 bool
 pgagroal_connection_isvalid(int socket);