Move extern function comments to headers.

This has been the policy for some time but due to migration pressure only new functions and refactors have been following this rule. Now it seems sensible to make a clean sweep and move all the comments that have not been moved already (i.e. most of them).

Only obvious typos and gross inaccuracies in the comments have been fixed. For this most part this was a copy and paste operation.

Useless comments, e.g. "New object", were not copied. Even so, there are surely many deficient comments left.

Some rearranging was done where needed and functions were placed in the proper sections, e.g. "Constructors", "Functions", etc.

A few function prototypes were found that not longer had an implementation. These were removed, but there may be more.

The coding document has been updated to reflect this policy, which is not new but has never been documented.

CODING.md

@@ -30,6 +30,10 @@ if (archiveInfoPgHistory.id != backupInfoPgHistory.id || archiveInfoPgHistory.sy
     backupInfoPgHistory.systemId || archiveInfoPgHistory.version != backupInfoPgHistory.version)
 ```
 
+### Function Comments
+
+Comments for `extern` functions should be included in the `.h` file. Comments for `static` functions and implementation-specific notes for `extern` functions (i.e., not of interest to the general user) should be included in the `.c` file.
+
 ### Inline Comment
 
 Inline comments shall start at character 69 and must not exceed the line length of 132. For example:

doc/xml/coding.xml

@@ -41,6 +41,12 @@ if (archiveInfoPgHistory.id != backupInfoPgHistory.id || archiveInfoPgHistory.sy
             </code-block>
         </section>
 
+        <section id="function-comment">
+            <title>Function Comments</title>
+
+            <p>Comments for <code>extern</code> functions should be included in the <file>.h</file> file. Comments for <code>static</code> functions and implementation-specific notes for <code>extern</code> functions (i.e., not of interest to the general user) should be included in the <file>.c</file> file.</p>
+        </section>
+
         <section id="inline-comment">
             <title>Inline Comment</title>
 

src/command/archive/common.c

@@ -67,9 +67,7 @@ archiveAsyncErrorClear(ArchiveMode archiveMode, const String *archiveFile)
     FUNCTION_LOG_RETURN_VOID();
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Check for ok/error status files in the spool in/out directory
-***********************************************************************************************************************************/
 bool
 archiveAsyncStatus(ArchiveMode archiveMode, const String *walSegment, bool throwOnError)
 {
@@ -172,9 +170,7 @@ archiveAsyncStatus(ArchiveMode archiveMode, const String *walSegment, bool throw
     FUNCTION_LOG_RETURN(BOOL, result);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Write an error status file
-***********************************************************************************************************************************/
 void
 archiveAsyncStatusErrorWrite(ArchiveMode archiveMode, const String *walSegment, int code, const String *message)
 {
@@ -203,9 +199,7 @@ archiveAsyncStatusErrorWrite(ArchiveMode archiveMode, const String *walSegment,
     FUNCTION_LOG_RETURN_VOID();
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Write an ok status file
-***********************************************************************************************************************************/
 void
 archiveAsyncStatusOkWrite(ArchiveMode archiveMode, const String *walSegment, const String *warning)
 {
@@ -282,9 +276,7 @@ archiveAsyncExec(ArchiveMode archiveMode, const StringList *commandExec)
     FUNCTION_LOG_RETURN_VOID();
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Is the segment partial?
-***********************************************************************************************************************************/
 bool
 walIsPartial(const String *walSegment)
 {
@@ -298,9 +290,7 @@ walIsPartial(const String *walSegment)
     FUNCTION_LOG_RETURN(BOOL, strEndsWithZ(walSegment, WAL_SEGMENT_PARTIAL_EXT));
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Generates the location of the wal directory using a relative wal path and the supplied pg path
-***********************************************************************************************************************************/
 String *
 walPath(const String *walFile, const String *pgPath, const String *command)
 {
@@ -356,9 +346,7 @@ walPath(const String *walFile, const String *pgPath, const String *command)
     FUNCTION_LOG_RETURN(STRING, result);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Is the file a segment or some other file (e.g. .history, .backup, etc)
-***********************************************************************************************************************************/
 bool
 walIsSegment(const String *walSegment)
 {
@@ -383,12 +371,7 @@ walIsSegment(const String *walSegment)
     FUNCTION_LOG_RETURN(BOOL, regExpMatch(regExpSegment, walSegment));
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Find a WAL segment in the repository
-
-The file name can have several things appended such as a hash, compression extension, and partial extension so it is possible to
-have multiple files that match the segment, though more than one match is not a good thing.
-***********************************************************************************************************************************/
 String *
 walSegmentFind(const Storage *storage, const String *archiveId, const String *walSegment, TimeMSec timeout)
 {
@@ -456,9 +439,7 @@ walSegmentFind(const Storage *storage, const String *archiveId, const String *wa
     FUNCTION_LOG_RETURN(STRING, result);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Get the next WAL segment given a WAL segment and WAL segment size
-***********************************************************************************************************************************/
 String *
 walSegmentNext(const String *walSegment, size_t walSegmentSize, unsigned int pgVersion)
 {
@@ -505,9 +486,7 @@ walSegmentNext(const String *walSegment, size_t walSegmentSize, unsigned int pgV
     FUNCTION_LOG_RETURN(STRING, strNewFmt("%08X%08X%08X", timeline, major, minor));
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Build a list of WAL segments based on a beginning WAL and number of WAL in the range (inclusive)
-***********************************************************************************************************************************/
 StringList *
 walSegmentRange(const String *walSegmentBegin, size_t walSegmentSize, unsigned int pgVersion, unsigned int range)
 {

src/command/archive/common.h

@@ -63,18 +63,36 @@ Functions
 // old error may be reported rather than waiting for the async process to succeed or fail.
 void archiveAsyncErrorClear(ArchiveMode archiveMode, const String *archiveFile);
 
+// Check for ok/error status files in the spool in/out directory
 bool archiveAsyncStatus(ArchiveMode archiveMode, const String *walSegment, bool throwOnError);
+
+// Write an ok status file
 void archiveAsyncStatusOkWrite(ArchiveMode archiveMode, const String *walSegment, const String *warning);
+
+// Write an error status file
 void archiveAsyncStatusErrorWrite(ArchiveMode archiveMode, const String *walSegment, int code, const String *message);
 
 // Execute the async process.  This function will only return in the calling process and the implementation is platform depedent.
 void archiveAsyncExec(ArchiveMode archiveMode, const StringList *commandExec);
 
+// Is the segment partial?
 bool walIsPartial(const String *walSegment);
+
+// Is the file a segment or some other file (e.g. .history, .backup, etc)
 bool walIsSegment(const String *walSegment);
+
+// Generates the location of the wal directory using a relative wal path and the supplied pg path
 String *walPath(const String *walFile, const String *pgPath, const String *command);
+
+// Find a WAL segment in the repository. The file name can have several things appended such as a hash, compression extension, and
+// partial extension so it is possible to have multiple files that match the segment, though more than one match is not a good
+// thing.
 String *walSegmentFind(const Storage *storage, const String *archiveId, const String *walSegment, TimeMSec timeout);
+
+// Get the next WAL segment given a WAL segment and WAL segment size
 String *walSegmentNext(const String *walSegment, size_t walSegmentSize, unsigned int pgVersion);
+
+// Build a list of WAL segments based on a beginning WAL and number of WAL in the range (inclusive)
 StringList *walSegmentRange(const String *walSegmentBegin, size_t walSegmentSize, unsigned int pgVersion, unsigned int range);
 
 #endif

src/command/archive/get/file.c

@@ -109,9 +109,7 @@ archiveGetCheck(const String *archiveFile, CipherType cipherType, const String *
     FUNCTION_LOG_RETURN(ARCHIVE_GET_CHECK_RESULT, result);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Copy a file from the archive to the specified destination
-***********************************************************************************************************************************/
 int
 archiveGetFile(
     const Storage *storage, const String *archiveFile, const String *walDestination, bool durable, CipherType cipherType,

src/command/archive/get/file.h

@@ -11,6 +11,7 @@ Archive Get File
 /***********************************************************************************************************************************
 Functions
 ***********************************************************************************************************************************/
+// Copy a file from the archive to the specified destination
 int archiveGetFile(
     const Storage *storage, const String *archiveFile, const String *walDestination, bool durable, CipherType cipherType,
     const String *cipherPass);

src/command/archive/get/get.c

@@ -99,9 +99,7 @@ queueNeed(const String *walSegment, bool found, uint64_t queueSize, size_t walSe
     FUNCTION_LOG_RETURN(STRING_LIST, result);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Get an archive file from the repository (WAL segment, history file, etc.)
-***********************************************************************************************************************************/
 int
 cmdArchiveGet(void)
 {
@@ -277,9 +275,7 @@ cmdArchiveGet(void)
     FUNCTION_LOG_RETURN(INT, result);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Async version of archive get that runs in parallel for performance
-***********************************************************************************************************************************/
 typedef struct ArchiveGetAsyncData
 {
     const StringList *walSegmentList;                               // List of wal segments to process

src/command/archive/get/get.h

@@ -7,7 +7,10 @@ Archive Get Command
 /***********************************************************************************************************************************
 Functions
 ***********************************************************************************************************************************/
+// Get an archive file from the repository (WAL segment, history file, etc.)
 int cmdArchiveGet(void);
+
+// Async version of archive get that runs in parallel for performance
 void cmdArchiveGetAsync(void);
 
 #endif

src/command/archive/get/protocol.c

@@ -17,9 +17,7 @@ Constants
 ***********************************************************************************************************************************/
 STRING_EXTERN(PROTOCOL_COMMAND_ARCHIVE_GET_STR,                     PROTOCOL_COMMAND_ARCHIVE_GET);
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Process protocol requests
-***********************************************************************************************************************************/
 bool
 archiveGetProtocol(const String *command, const VariantList *paramList, ProtocolServer *server)
 {

src/command/archive/get/protocol.h

@@ -17,6 +17,7 @@ Constants
 /***********************************************************************************************************************************
 Functions
 ***********************************************************************************************************************************/
+// Process protocol requests
 bool archiveGetProtocol(const String *command, const VariantList *paramList, ProtocolServer *server);
 
 #endif

src/command/archive/push/file.c

@@ -16,9 +16,7 @@ Archive Push File
 #include "postgres/interface.h"
 #include "storage/helper.h"
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Copy a file from the source to the archive
-***********************************************************************************************************************************/
 String *
 archivePushFile(
     const String *walSource, const String *archiveId, unsigned int pgVersion, uint64_t pgSystemId, const String *archiveFile,

src/command/archive/push/file.h

@@ -12,6 +12,7 @@ Archive Push File
 /***********************************************************************************************************************************
 Functions
 ***********************************************************************************************************************************/
+// Copy a file from the source to the archive
 String *archivePushFile(
     const String *walSource, const String *archiveId, unsigned int pgVersion, uint64_t pgSystemId, const String *archiveFile,
     CipherType cipherType, const String *cipherPass, CompressType compressType, int compressLevel);

src/command/archive/push/protocol.c

@@ -17,9 +17,7 @@ Constants
 ***********************************************************************************************************************************/
 STRING_EXTERN(PROTOCOL_COMMAND_ARCHIVE_PUSH_STR,                     PROTOCOL_COMMAND_ARCHIVE_PUSH);
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Process protocol requests
-***********************************************************************************************************************************/
 bool
 archivePushProtocol(const String *command, const VariantList *paramList, ProtocolServer *server)
 {

src/command/archive/push/protocol.h

@@ -17,6 +17,7 @@ Constants
 /***********************************************************************************************************************************
 Functions
 ***********************************************************************************************************************************/
+// Process protocol requests
 bool archivePushProtocol(const String *command, const VariantList *paramList, ProtocolServer *server);
 
 #endif

src/command/archive/push/push.c

@@ -248,9 +248,7 @@ archivePushCheck(CipherType cipherType, const String *cipherPass)
     FUNCTION_LOG_RETURN(ARCHIVE_PUSH_CHECK_RESULT, result);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Push a WAL segment to the repository
-***********************************************************************************************************************************/
 void
 cmdArchivePush(void)
 {
@@ -376,9 +374,7 @@ cmdArchivePush(void)
     FUNCTION_LOG_RETURN_VOID();
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Async version of archive push that runs in parallel for performance
-***********************************************************************************************************************************/
 typedef struct ArchivePushAsyncData
 {
     const String *walPath;                                          // Path to pg_wal/pg_xlog

src/command/archive/push/push.h

@@ -7,7 +7,10 @@ Archive Push Command
 /***********************************************************************************************************************************
 Functions
 ***********************************************************************************************************************************/
+// Push a WAL segment to the repository
 void cmdArchivePush(void);
+
+// Async version of archive push that runs in parallel for performance
 void cmdArchivePushAsync(void);
 
 #endif

src/command/backup/backup.c

@@ -1929,9 +1929,7 @@ backupComplete(InfoBackup *const infoBackup, Manifest *const manifest)
     FUNCTION_LOG_RETURN_VOID();
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Make a backup
-***********************************************************************************************************************************/
 void
 cmdBackup(void)
 {

src/command/backup/backup.h

@@ -7,6 +7,7 @@ Backup Command
 /***********************************************************************************************************************************
 Functions
 ***********************************************************************************************************************************/
+// Make a backup
 void cmdBackup(void);
 
 #endif

src/command/backup/common.c

@@ -16,9 +16,7 @@ STRING_EXTERN(BACKUP_TYPE_FULL_STR,                                 BACKUP_TYPE_
 STRING_EXTERN(BACKUP_TYPE_DIFF_STR,                                 BACKUP_TYPE_DIFF);
 STRING_EXTERN(BACKUP_TYPE_INCR_STR,                                 BACKUP_TYPE_INCR);
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Returns an anchored regex string for filtering backups based on the type (at least one type is required to be true)
-***********************************************************************************************************************************/
 String *
 backupRegExp(BackupRegExpParam param)
 {
@@ -83,9 +81,7 @@ backupRegExp(BackupRegExpParam param)
     FUNCTION_LOG_RETURN(STRING, result);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Convert text backup type to an enum and back
-***********************************************************************************************************************************/
 BackupType
 backupType(const String *type)
 {

src/command/backup/common.h

@@ -26,8 +26,9 @@ typedef enum
     STRING_DECLARE(BACKUP_TYPE_INCR_STR);
 
 /***********************************************************************************************************************************
-Returns an anchored regex string for filtering backups based on the type (at least one type is required to be true)
+Functions
 ***********************************************************************************************************************************/
+// Returns an anchored regex string for filtering backups based on the type (at least one type is required to be true)
 typedef struct BackupRegExpParam
 {
     bool full;
@@ -41,9 +42,7 @@ typedef struct BackupRegExpParam
 
 String *backupRegExp(BackupRegExpParam param);
 
-/***********************************************************************************************************************************
+// Convert text backup type to an enum and back
-Convert text backup type to an enum and back
-***********************************************************************************************************************************/
 BackupType backupType(const String *type);
 const String *backupTypeStr(BackupType type);
 

src/command/backup/file.c

@@ -33,9 +33,7 @@ segmentNumber(const String *pgFile)
     FUNCTION_TEST_RETURN(regExpMatchOne(STRDEF("\\.[0-9]+$"), pgFile) ? cvtZToUInt(strrchr(strPtr(pgFile), '.') + 1) : 0);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Copy a file from the PostgreSQL data directory to the repository
-***********************************************************************************************************************************/
 BackupFileResult
 backupFile(
     const String *pgFile, bool pgFileIgnoreMissing, uint64_t pgFileSize, const String *pgFileChecksum, bool pgFileChecksumPage,

src/command/backup/file.h

@@ -23,6 +23,7 @@ typedef enum
 /***********************************************************************************************************************************
 Functions
 ***********************************************************************************************************************************/
+// Copy a file from the PostgreSQL data directory to the repository
 typedef struct BackupFileResult
 {
     BackupCopyResult backupCopyResult;

src/command/backup/pageChecksum.c

@@ -216,9 +216,7 @@ pageChecksumResult(THIS_VOID)
     FUNCTION_LOG_RETURN(VARIANT, varNewKv(result));
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-New object
-***********************************************************************************************************************************/
 IoFilter *
 pageChecksumNew(unsigned int segmentNo, unsigned int segmentPageTotal, uint64_t lsnLimit)
 {

src/command/backup/pageChecksum.h

@@ -15,7 +15,7 @@ Filter type constant
     STRING_DECLARE(PAGE_CHECKSUM_FILTER_TYPE_STR);
 
 /***********************************************************************************************************************************
-Constructor
+Constructors
 ***********************************************************************************************************************************/
 IoFilter *pageChecksumNew(unsigned int segmentNo, unsigned int segmentPageTotal, uint64_t lsnLimit);
 IoFilter *pageChecksumNewVar(const VariantList *paramList);

src/command/backup/protocol.c

@@ -17,9 +17,7 @@ Constants
 ***********************************************************************************************************************************/
 STRING_EXTERN(PROTOCOL_COMMAND_BACKUP_FILE_STR,                     PROTOCOL_COMMAND_BACKUP_FILE);
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Process protocol requests
-***********************************************************************************************************************************/
 bool
 backupProtocol(const String *command, const VariantList *paramList, ProtocolServer *server)
 {

src/command/backup/protocol.h

@@ -17,6 +17,7 @@ Constants
 /***********************************************************************************************************************************
 Functions
 ***********************************************************************************************************************************/
+// Process protocol requests
 bool backupProtocol(const String *command, const VariantList *paramList, ProtocolServer *server);
 
 #endif

src/command/check/check.c

@@ -144,9 +144,7 @@ checkPrimary(const DbGetResult dbGroup)
     FUNCTION_LOG_RETURN_VOID();
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Perform standard checks
-***********************************************************************************************************************************/
 void
 cmdCheck(void)
 {

src/command/check/check.h

@@ -7,6 +7,7 @@ Check Command
 /***********************************************************************************************************************************
 Functions
 ***********************************************************************************************************************************/
+// Perform standard checks
 void cmdCheck(void);
 
 #endif

src/command/check/common.c

@@ -40,9 +40,7 @@ checkArchiveCommand(const String *archiveCommand)
     FUNCTION_TEST_RETURN(result);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Check the database path and version are configured correctly
-***********************************************************************************************************************************/
 void
 checkDbConfig(const unsigned int pgVersion, const unsigned int dbIdx, const Db *dbObject, bool isStandby)
 {
@@ -96,9 +94,7 @@ checkDbConfig(const unsigned int pgVersion, const unsigned int dbIdx, const Db *
     FUNCTION_TEST_RETURN_VOID();
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Validate the archive and backup info files
-***********************************************************************************************************************************/
 void
 checkStanzaInfo(const InfoPgData *archiveInfo, const InfoPgData *backupInfo)
 {
@@ -126,9 +122,7 @@ checkStanzaInfo(const InfoPgData *archiveInfo, const InfoPgData *backupInfo)
     FUNCTION_TEST_RETURN_VOID();
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Load and validate the database data of the info files against each other and the current database
-***********************************************************************************************************************************/
 void
 checkStanzaInfoPg(
     const Storage *storage, const unsigned int pgVersion, const uint64_t pgSystemId, CipherType cipherType,

src/command/check/common.h

@@ -11,8 +11,13 @@ Check Command Common
 /***********************************************************************************************************************************
 Functions
 ***********************************************************************************************************************************/
+// Check the database path and version are configured correctly
 void checkDbConfig(const unsigned int pgVersion, const unsigned int dbIdx, const Db *dbObject, bool isStandby);
+
+// Validate the archive and backup info files
 void checkStanzaInfo(const InfoPgData *archiveInfo, const InfoPgData *backupInfo);
+
+// Load and validate the database data of the info files against each other and the current database
 void checkStanzaInfoPg(
     const Storage *storage, const unsigned int pgVersion, const uint64_t pgSystemId, CipherType cipherType,
     const String *cipherPass);

src/command/command.c

@@ -20,9 +20,7 @@ Track time command started
 ***********************************************************************************************************************************/
 static TimeMSec timeBegin;
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Capture time at the very start of main so total time is more accurate
-***********************************************************************************************************************************/
 void
 cmdInit(void)
 {
@@ -33,9 +31,7 @@ cmdInit(void)
     FUNCTION_LOG_RETURN_VOID();
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Begin the command
-***********************************************************************************************************************************/
 void
 cmdBegin(bool logOption)
 {
@@ -168,9 +164,7 @@ cmdBegin(bool logOption)
     FUNCTION_LOG_RETURN_VOID();
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-End the command
-***********************************************************************************************************************************/
 void
 cmdEnd(int code, const String *errorMessage)
 {

src/command/command.h

@@ -9,9 +9,13 @@ Common Command Routines
 /***********************************************************************************************************************************
 Functions
 ***********************************************************************************************************************************/
+// Capture time at the very start of main so total time is more accurate
 void cmdInit(void);
 
+// Begin the command
 void cmdBegin(bool logOption);
+
+// End the command
 void cmdEnd(int code, const String *errorMessage);
 
 #endif

src/command/control/common.c

@@ -8,9 +8,7 @@ Common Handler for Control Commands
 #include "config/config.h"
 #include "storage/helper.h"
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Create the stop filename
-***********************************************************************************************************************************/
 String *
 lockStopFileName(const String *stanza)
 {
@@ -24,9 +22,7 @@ lockStopFileName(const String *stanza)
     FUNCTION_TEST_RETURN(result);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Test for the existence of a stop file
-***********************************************************************************************************************************/
 void
 lockStopTest(void)
 {

src/command/control/common.h

@@ -14,7 +14,10 @@ Constants
 /***********************************************************************************************************************************
 Functions
 ***********************************************************************************************************************************/
+// Create the stop filename
 String *lockStopFileName(const String *stanza);
+
+// Test for the existence of a stop file
 void lockStopTest(void);
 
 #endif

src/command/control/start.c

@@ -9,6 +9,7 @@ Start Command
 #include "storage/helper.h"
 #include "storage/storage.h"
 
+/**********************************************************************************************************************************/
 void
 cmdStart(void)
 {

src/command/control/stop.c

@@ -18,6 +18,7 @@ Stop Command
 #include "storage/storage.h"
 #include "storage/storage.intern.h"
 
+/**********************************************************************************************************************************/
 void
 cmdStop(void)
 {

src/command/expire/expire.c

@@ -634,9 +634,7 @@ removeExpiredBackup(InfoBackup *infoBackup)
     FUNCTION_LOG_RETURN_VOID();
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Expire backups and archives
-***********************************************************************************************************************************/
 void
 cmdExpire(void)
 {

src/command/expire/expire.h

@@ -7,6 +7,7 @@ Expire Command
 /***********************************************************************************************************************************
 Functions
 ***********************************************************************************************************************************/
+// Expire backups and archives
 void cmdExpire(void);
 
 #endif

src/command/help/help.c

@@ -365,9 +365,7 @@ helpRender(void)
     FUNCTION_LOG_RETURN(STRING, result);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Render help and output to stdout
-***********************************************************************************************************************************/
 void
 cmdHelp(void)
 {

src/command/help/help.h

@@ -7,6 +7,7 @@ Help Command
 /***********************************************************************************************************************************
 Functions
 ***********************************************************************************************************************************/
+// Render help and output to stdout
 void cmdHelp(void);
 
 #endif

src/command/info/info.c

@@ -813,9 +813,7 @@ infoRender(void)
     FUNCTION_LOG_RETURN(STRING, result);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Render info and output to stdout
-***********************************************************************************************************************************/
 void
 cmdInfo(void)
 {

src/command/info/info.h

@@ -7,6 +7,7 @@ Info Command
 /***********************************************************************************************************************************
 Functions
 ***********************************************************************************************************************************/
+// Render info and output to stdout
 void cmdInfo(void);
 
 #endif

src/command/local/local.c

@@ -16,9 +16,7 @@ Local Command
 #include "protocol/helper.h"
 #include "protocol/server.h"
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Remote command
-***********************************************************************************************************************************/
 void
 cmdLocal(int handleRead, int handleWrite)
 {

src/command/local/local.h

@@ -7,6 +7,7 @@ Local Command
 /***********************************************************************************************************************************
 Functions
 ***********************************************************************************************************************************/
+// Local command
 void cmdLocal(int handleRead, int handleWrite);
 
 #endif

src/command/remote/remote.c

@@ -17,9 +17,7 @@ Remote Command
 #include "protocol/server.h"
 #include "storage/remote/protocol.h"
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Remote command
-***********************************************************************************************************************************/
 void
 cmdRemote(int handleRead, int handleWrite)
 {

src/command/remote/remote.h

@@ -7,6 +7,7 @@ Remote Command
 /***********************************************************************************************************************************
 Functions
 ***********************************************************************************************************************************/
+// Remote command
 void cmdRemote(int handleRead, int handleWrite);
 
 #endif

src/command/restore/file.c

@@ -18,9 +18,7 @@ Restore File
 #include "config/config.h"
 #include "storage/helper.h"
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Copy a file from the backup to the specified destination
-***********************************************************************************************************************************/
 bool
 restoreFile(
     const String *repoFile, const String *repoFileReference, CompressType repoFileCompressType, const String *pgFile,

src/command/restore/file.h

@@ -12,6 +12,7 @@ Restore File
 /***********************************************************************************************************************************
 Functions
 ***********************************************************************************************************************************/
+// Copy a file from the backup to the specified destination
 bool restoreFile(
     const String *repoFile, const String *repoFileReference, CompressType repoFileCompressType, const String *pgFile,
     const String *pgFileChecksum, bool pgFileZero, uint64_t pgFileSize, time_t pgFileModified, mode_t pgFileMode,

src/command/restore/protocol.c

@@ -17,9 +17,7 @@ Constants
 ***********************************************************************************************************************************/
 STRING_EXTERN(PROTOCOL_COMMAND_RESTORE_FILE_STR,                    PROTOCOL_COMMAND_RESTORE_FILE);
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Process protocol requests
-***********************************************************************************************************************************/
 bool
 restoreProtocol(const String *command, const VariantList *paramList, ProtocolServer *server)
 {

src/command/restore/protocol.h

@@ -17,6 +17,7 @@ Constants
 /***********************************************************************************************************************************
 Functions
 ***********************************************************************************************************************************/
+// Process protocol requests
 bool restoreProtocol(const String *command, const VariantList *paramList, ProtocolServer *server);
 
 #endif

src/command/restore/restore.c

@@ -1995,9 +1995,7 @@ static ProtocolParallelJob *restoreJobCallback(void *data, unsigned int clientId
     FUNCTION_TEST_RETURN(result);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Restore a backup
-***********************************************************************************************************************************/
 void
 cmdRestore(void)
 {

src/command/restore/restore.h

@@ -7,6 +7,7 @@ Restore Command
 /***********************************************************************************************************************************
 Functions
 ***********************************************************************************************************************************/
+// Restore a backup
 void cmdRestore(void);
 
 #endif

src/command/stanza/common.c

@@ -14,9 +14,7 @@ Stanza Commands Handler
 #include "postgres/version.h"
 #include "storage/helper.h"
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Generate a cipher
-***********************************************************************************************************************************/
 String *
 cipherPassGen(CipherType cipherType)
 {
@@ -38,9 +36,7 @@ cipherPassGen(CipherType cipherType)
     FUNCTION_TEST_RETURN(result);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Validate and return database information
-***********************************************************************************************************************************/
 PgControl
 pgValidate(void)
 {

src/command/stanza/common.h

@@ -10,7 +10,10 @@ Stanza Commands Handler
 /***********************************************************************************************************************************
 Functions
 ***********************************************************************************************************************************/
+// Generate a cipher
 String *cipherPassGen(CipherType cipherType);
+
+// Validate and return database information
 PgControl pgValidate(void);
 
 #endif

src/command/stanza/create.c

@@ -23,9 +23,7 @@ Stanza Create Command
 #include "protocol/helper.h"
 #include "storage/helper.h"
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Process stanza-create
-***********************************************************************************************************************************/
 void
 cmdStanzaCreate(void)
 {

src/command/stanza/create.h

@@ -7,6 +7,7 @@ Stanza Create Command
 /***********************************************************************************************************************************
 Functions
 ***********************************************************************************************************************************/
+// Process stanza-create
 void cmdStanzaCreate(void);
 
 #endif

src/command/stanza/delete.c

@@ -127,9 +127,7 @@ stanzaDelete(const Storage *storageRepoWriteStanza, const StringList *archiveLis
     FUNCTION_TEST_RETURN(result);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Process stanza-delete
-***********************************************************************************************************************************/
 void
 cmdStanzaDelete(void)
 {

src/command/stanza/delete.h

@@ -7,6 +7,7 @@ Stanza Delete Command
 /***********************************************************************************************************************************
 Functions
 ***********************************************************************************************************************************/
+// Process stanza-delete
 void cmdStanzaDelete(void);
 
 #endif

src/command/stanza/upgrade.c

@@ -23,9 +23,7 @@ Stanza Update Command
 #include "protocol/helper.h"
 #include "storage/helper.h"
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Process stanza-upgrade
-***********************************************************************************************************************************/
 void
 cmdStanzaUpgrade(void)
 {

src/command/stanza/upgrade.h

@@ -7,6 +7,7 @@ Stanza Upgrade Command
 /***********************************************************************************************************************************
 Functions
 ***********************************************************************************************************************************/
+// Process stanza-upgrade
 void cmdStanzaUpgrade(void);
 
 #endif

src/common/compress/gz/common.c

@@ -9,9 +9,7 @@ Gz Common
 #include "common/debug.h"
 #include "common/memContext.h"
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Process gz errors
-***********************************************************************************************************************************/
 int
 gzError(int error)
 {

src/common/compress/gz/common.h

@@ -18,6 +18,7 @@ Constants
 /***********************************************************************************************************************************
 Functions
 ***********************************************************************************************************************************/
+// Process gz errors
 int gzError(int error);
 
 #endif

src/common/compress/gz/compress.c

@@ -158,9 +158,7 @@ gzCompressInputSame(const THIS_VOID)
     FUNCTION_TEST_RETURN(this->inputSame);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-New object
-***********************************************************************************************************************************/
 IoFilter *
 gzCompressNew(int level)
 {

src/common/compress/gz/decompress.c

@@ -141,9 +141,7 @@ gzDecompressInputSame(const THIS_VOID)
     FUNCTION_TEST_RETURN(this->inputSame);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-New object
-***********************************************************************************************************************************/
 IoFilter *
 gzDecompressNew(void)
 {

src/common/compress/lz4/common.c

@@ -10,9 +10,7 @@ LZ4 Common
 #include "common/compress/lz4/common.h"
 #include "common/debug.h"
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Process lz4 errors
-***********************************************************************************************************************************/
 LZ4F_errorCode_t
 lz4Error(LZ4F_errorCode_t error)
 {

src/common/compress/lz4/common.h

@@ -14,6 +14,7 @@ LZ4 extension
 /***********************************************************************************************************************************
 Functions
 ***********************************************************************************************************************************/
+// Process lz4 errors
 size_t lz4Error(size_t error);
 
 #endif // HAVE_LIBLZ4

src/common/compress/lz4/compress.c

@@ -237,9 +237,7 @@ lz4CompressInputSame(const THIS_VOID)
     FUNCTION_TEST_RETURN(this->inputSame);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-New object
-***********************************************************************************************************************************/
 IoFilter *
 lz4CompressNew(int level)
 {

src/common/compress/lz4/decompress.c

@@ -155,9 +155,7 @@ lz4DecompressInputSame(const THIS_VOID)
     FUNCTION_TEST_RETURN(this->inputSame);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-New object
-***********************************************************************************************************************************/
 IoFilter *
 lz4DecompressNew(void)
 {

src/common/crypto/cipherBlock.c

@@ -380,9 +380,7 @@ cipherBlockInputSame(const THIS_VOID)
     FUNCTION_TEST_RETURN(this->inputSame);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-New block encrypt/decrypt object
-***********************************************************************************************************************************/
 IoFilter *
 cipherBlockNew(CipherMode mode, CipherType cipherType, const Buffer *pass, const String *digestName)
 {
@@ -464,9 +462,7 @@ cipherBlockNewVar(const VariantList *paramList)
         BUFSTR(varStr(varLstGet(paramList, 2))), varLstGet(paramList, 3) == NULL ? NULL : varStr(varLstGet(paramList, 3)));
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Helper function to add a block cipher to an io object
-***********************************************************************************************************************************/
 IoFilterGroup *
 cipherBlockFilterGroupAdd(IoFilterGroup *filterGroup, CipherType type, CipherMode mode, const String *pass)
 {

src/common/crypto/cipherBlock.h

@@ -14,7 +14,7 @@ Filter type constant
     STRING_DECLARE(CIPHER_BLOCK_FILTER_TYPE_STR);
 
 /***********************************************************************************************************************************
-Constructor
+Constructors
 ***********************************************************************************************************************************/
 IoFilter *cipherBlockNew(CipherMode mode, CipherType cipherType, const Buffer *pass, const String *digestName);
 IoFilter *cipherBlockNewVar(const VariantList *paramList);
@@ -22,6 +22,7 @@ IoFilter *cipherBlockNewVar(const VariantList *paramList);
 /***********************************************************************************************************************************
 Helper functions
 ***********************************************************************************************************************************/
+// Add a block cipher to an io object
 IoFilterGroup *cipherBlockFilterGroupAdd(IoFilterGroup *filterGroup, CipherType type, CipherMode mode, const String *pass);
 
 #endif

src/common/crypto/common.c

@@ -25,9 +25,7 @@ Flag to indicate if OpenSSL has already been initialized
 ***********************************************************************************************************************************/
 static bool cryptoInitDone = false;
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Throw crypto errors
-***********************************************************************************************************************************/
 void
 cryptoError(bool error, const char *description)
 {
@@ -56,9 +54,7 @@ cryptoErrorCode(unsigned long code, const char *description)
     FUNCTION_TEST_RETURN_VOID();
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Get cipher type or name
-***********************************************************************************************************************************/
 CipherType
 cipherType(const String *name)
 {
@@ -95,9 +91,7 @@ cipherTypeName(CipherType type)
     FUNCTION_TEST_RETURN(result);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Initialize crypto
-***********************************************************************************************************************************/
 void
 cryptoInit(void)
 {
@@ -125,9 +119,7 @@ cryptoInit(void)
     FUNCTION_LOG_RETURN_VOID();
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Has crypto been initialized?
-***********************************************************************************************************************************/
 bool
 cryptoIsInit(void)
 {
@@ -135,9 +127,7 @@ cryptoIsInit(void)
     FUNCTION_TEST_RETURN(cryptoInitDone);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Generate random bytes
-***********************************************************************************************************************************/
 void
 cryptoRandomBytes(unsigned char *buffer, size_t size)
 {

src/common/crypto/common.h

@@ -32,15 +32,21 @@ typedef enum
 /***********************************************************************************************************************************
 Functions
 ***********************************************************************************************************************************/
+// Initialize crypto
 void cryptoInit(void);
+
+// Has crypto been initialized?
 bool cryptoIsInit(void);
 
+// Throw crypto errors
 void cryptoError(bool error, const char *description);
 void cryptoErrorCode(unsigned long code, const char *description) __attribute__((__noreturn__));
 
+// Get cipher type or name
 CipherType cipherType(const String *name);
 const String *cipherTypeName(CipherType type);
 
+// Generate random bytes
 void cryptoRandomBytes(unsigned char *buffer, size_t size);
 
 #endif

src/common/crypto/hash.c

@@ -133,9 +133,7 @@ cryptoHashResult(THIS_VOID)
     FUNCTION_LOG_RETURN(VARIANT, varNewStr(bufHex(cryptoHash(this))));
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-New object
-***********************************************************************************************************************************/
 IoFilter *
 cryptoHashNew(const String *type)
 {
@@ -191,9 +189,7 @@ cryptoHashNewVar(const VariantList *paramList)
     return cryptoHashNew(varStr(varLstGet(paramList, 0)));
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Get hash for one C buffer
-***********************************************************************************************************************************/
 Buffer *
 cryptoHashOne(const String *type, const Buffer *message)
 {
@@ -227,9 +223,7 @@ cryptoHashOne(const String *type, const Buffer *message)
     FUNCTION_LOG_RETURN(BUFFER, result);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Get hmac for one message/key
-***********************************************************************************************************************************/
 Buffer *
 cryptoHmacOne(const String *type, const Buffer *key, const Buffer *message)
 {

src/common/crypto/hash.h

@@ -48,7 +48,7 @@ Hash type sizes
 #define HASH_TYPE_SHA256_SIZE_HEX                                   (HASH_TYPE_SHA256_SIZE * 2)
 
 /***********************************************************************************************************************************
-Constructor
+Constructors
 ***********************************************************************************************************************************/
 IoFilter *cryptoHashNew(const String *type);
 IoFilter *cryptoHashNewVar(const VariantList *paramList);
@@ -56,7 +56,10 @@ IoFilter *cryptoHashNewVar(const VariantList *paramList);
 /***********************************************************************************************************************************
 Helper functions
 ***********************************************************************************************************************************/
+// Get hash for one buffer
 Buffer *cryptoHashOne(const String *type, const Buffer *message);
+
+// Get hmac for one message/key
 Buffer *cryptoHmacOne(const String *type, const Buffer *key, const Buffer *message);
 
 #endif

src/common/debug.c

@@ -7,9 +7,7 @@ Debug Routines
 
 #include "common/debug.h"
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Convert object to a zero-terminated string for logging
-***********************************************************************************************************************************/
 size_t
 objToLog(const void *object, const char *objectName, char *buffer, size_t bufferSize)
 {
@@ -23,9 +21,7 @@ objToLog(const void *object, const char *objectName, char *buffer, size_t buffer
     return result;
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Convert pointer to a zero-terminated string for logging
-***********************************************************************************************************************************/
 size_t
 ptrToLog(const void *pointer, const char *pointerName, char *buffer, size_t bufferSize)
 {
@@ -39,18 +35,14 @@ ptrToLog(const void *pointer, const char *pointerName, char *buffer, size_t buff
     return result;
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Convert zero-terminated string for logging
-***********************************************************************************************************************************/
 size_t
 strzToLog(const char *string, char *buffer, size_t bufferSize)
 {
     return (size_t)snprintf(buffer, bufferSize, string == NULL ? "%s" : "\"%s\"", string == NULL ? NULL_Z : string);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Convert a type name to a zero-terminated string for logging
-***********************************************************************************************************************************/
 size_t
 typeToLog(const char *typeName, char *buffer, size_t bufferSize)
 {

src/common/debug.h

@@ -114,9 +114,16 @@ FUNCTION_LOG_VOID() is provided as a shortcut for functions that have no paramet
 /***********************************************************************************************************************************
 Functions and macros to render various data types
 ***********************************************************************************************************************************/
+// Convert object to a zero-terminated string for logging
 size_t objToLog(const void *object, const char *objectName, char *buffer, size_t bufferSize);
+
+// Convert pointer to a zero-terminated string for logging
 size_t ptrToLog(const void *pointer, const char *pointerName, char *buffer, size_t bufferSize);
+
+// Convert zero-terminated string for logging
 size_t strzToLog(const char *string, char *buffer, size_t bufferSize);
+
+// Convert a type name to a zero-terminated string for logging
 size_t typeToLog(const char *typeName, char *buffer, size_t bufferSize);
 
 #define FUNCTION_LOG_BOOL_TYPE                                                                                                     \

src/common/encode.c

@@ -17,9 +17,7 @@ Macro to handle invalid encode type errors
 #define ENCODE_TYPE_INVALID_ERROR(encodeType)                                                                                      \
     THROW_FMT(AssertError, "invalid encode type %u", encodeType);
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Encode binary data to a printable string
-***********************************************************************************************************************************/
 void
 encodeToStr(EncodeType encodeType, const unsigned char *source, size_t sourceSize, char *destination)
 {
@@ -38,9 +36,7 @@ encodeToStr(EncodeType encodeType, const unsigned char *source, size_t sourceSiz
     FUNCTION_TEST_RETURN_VOID();
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Size of the string returned by encodeToStr()
-***********************************************************************************************************************************/
 size_t
 encodeToStrSize(EncodeType encodeType, size_t sourceSize)
 {
@@ -59,9 +55,7 @@ encodeToStrSize(EncodeType encodeType, size_t sourceSize)
     FUNCTION_TEST_RETURN(destinationSize);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Decode a string to binary data
-***********************************************************************************************************************************/
 void
 decodeToBin(EncodeType encodeType, const char *source, unsigned char *destination)
 {
@@ -79,9 +73,7 @@ decodeToBin(EncodeType encodeType, const char *source, unsigned char *destinatio
     FUNCTION_TEST_RETURN_VOID();
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Size of the binary data returned by decodeToBin()
-***********************************************************************************************************************************/
 size_t
 decodeToBinSize(EncodeType encodeType, const char *source)
 {
@@ -100,9 +92,7 @@ decodeToBinSize(EncodeType encodeType, const char *source)
     FUNCTION_TEST_RETURN(destinationSize);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Check that the encoded string is valid
-***********************************************************************************************************************************/
 bool
 decodeToBinValid(EncodeType encodeType, const char *source)
 {
@@ -126,9 +116,7 @@ decodeToBinValid(EncodeType encodeType, const char *source)
     FUNCTION_TEST_RETURN(valid);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Validate the encoded string
-***********************************************************************************************************************************/
 void
 decodeToBinValidate(EncodeType encodeType, const char *source)
 {

src/common/encode.h

@@ -9,16 +9,30 @@ These high-level functions are preferred to the low-level functions for each enc
 /***********************************************************************************************************************************
 Encoding types
 ***********************************************************************************************************************************/
-typedef enum {encodeBase64} EncodeType;
+typedef enum
+{
+    encodeBase64
+} EncodeType;
 
 /***********************************************************************************************************************************
 Functions
 ***********************************************************************************************************************************/
+// Encode binary data to a printable string
 void encodeToStr(EncodeType encodeType, const unsigned char *source, size_t sourceSize, char *destination);
+
+// Size of the string returned by encodeToStr()
 size_t encodeToStrSize(EncodeType encodeType, size_t sourceSize);
+
+// Decode a string to binary data
 void decodeToBin(EncodeType encodeType, const char *source, unsigned char *destination);
+
+// Size of the binary data returned by decodeToBin()
 size_t decodeToBinSize(EncodeType encodeType, const char *source);
+
+// Check that the encoded string is valid
 bool decodeToBinValid(EncodeType encodeType, const char *source);
+
+// Validate the encoded string
 void decodeToBinValidate(EncodeType encodeType, const char *source);
 
 #endif

src/common/encode/base64.c

@@ -9,9 +9,7 @@ Base64 Binary to String Encode/Decode
 #include "common/debug.h"
 #include "common/error.h"
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Encode binary data to a printable string
-***********************************************************************************************************************************/
 static const char encodeBase64Lookup[] = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
 
 void
@@ -72,9 +70,7 @@ encodeToStrBase64(const unsigned char *source, size_t sourceSize, char *destinat
     FUNCTION_TEST_RETURN_VOID();
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Size of the destination param required by encodeToStrBase64() minus space for the null terminator
-***********************************************************************************************************************************/
 size_t
 encodeToStrSizeBase64(size_t sourceSize)
 {
@@ -93,9 +89,7 @@ encodeToStrSizeBase64(size_t sourceSize)
     FUNCTION_TEST_RETURN(encodeGroupTotal * 4);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Decode a string to binary data
-***********************************************************************************************************************************/
 static const int decodeBase64Lookup[256] =
 {
     -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
@@ -154,9 +148,7 @@ decodeToBinBase64(const char *source, unsigned char *destination)
     FUNCTION_TEST_RETURN_VOID();
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Size of the destination param required by decodeToBinBase64()
-***********************************************************************************************************************************/
 size_t
 decodeToBinSizeBase64(const char *source)
 {
@@ -184,9 +176,7 @@ decodeToBinSizeBase64(const char *source)
     FUNCTION_TEST_RETURN(destinationSize);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Validate the encoded string
-***********************************************************************************************************************************/
 void
 decodeToBinValidateBase64(const char *source)
 {

src/common/encode/base64.h

@@ -9,10 +9,19 @@ The high-level functions in encode.c should be used in preference to these low-l
 /***********************************************************************************************************************************
 Functions
 ***********************************************************************************************************************************/
+// Encode binary data to a printable string
 void encodeToStrBase64(const unsigned char *source, size_t sourceSize, char *destination);
+
+// Size of the destination param required by encodeToStrBase64() minus space for the null terminator
 size_t encodeToStrSizeBase64(size_t sourceSize);
+
+// Decode a string to binary data
 void decodeToBinBase64(const char *source, unsigned char *destination);
+
+// Size of the destination param required by decodeToBinBase64()
 size_t decodeToBinSizeBase64(const char *source);
+
+// Validate the encoded string
 void decodeToBinValidateBase64(const char *source);
 
 #endif

src/common/error.c

@@ -88,18 +88,14 @@ static char messageBuffer[ERROR_MESSAGE_BUFFER_SIZE];
 static char messageBufferTemp[ERROR_MESSAGE_BUFFER_SIZE];
 static char stackTraceBuffer[ERROR_MESSAGE_BUFFER_SIZE];
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Error type code
-***********************************************************************************************************************************/
 int
 errorTypeCode(const ErrorType *errorType)
 {
     return errorType->code;
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Get error type using a code
-***********************************************************************************************************************************/
 const ErrorType *
 errorTypeFromCode(int code)
 {
@@ -122,35 +118,27 @@ errorTypeFromCode(int code)
     return result;
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Error type name
-***********************************************************************************************************************************/
 const char *
 errorTypeName(const ErrorType *errorType)
 {
     return errorType->name;
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Error type parent
-***********************************************************************************************************************************/
 const ErrorType *
 errorTypeParent(const ErrorType *errorType)
 {
     return errorType->parentType;
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Get the depth of the current try statement (0 if none)
-***********************************************************************************************************************************/
 unsigned int errorTryDepth(void)
 {
     return (unsigned int)errorContext.tryTotal;
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Does the child error type extend the parent error type?
-***********************************************************************************************************************************/
 bool
 errorTypeExtends(const ErrorType *child, const ErrorType *parent)
 {
@@ -170,81 +158,63 @@ errorTypeExtends(const ErrorType *child, const ErrorType *parent)
     return false;
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Error type
-***********************************************************************************************************************************/
 const ErrorType *
 errorType(void)
 {
     return errorContext.error.errorType;
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Error code (pulled from error type)
-***********************************************************************************************************************************/
 int
 errorCode(void)
 {
     return errorTypeCode(errorType());
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Error filename
-***********************************************************************************************************************************/
 const char *
 errorFileName(void)
 {
     return errorContext.error.fileName;
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Error function name
-***********************************************************************************************************************************/
 const char *
 errorFunctionName(void)
 {
     return errorContext.error.functionName;
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Error file line number
-***********************************************************************************************************************************/
 int
 errorFileLine(void)
 {
     return errorContext.error.fileLine;
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Error message
-***********************************************************************************************************************************/
 const char *
 errorMessage(void)
 {
     return errorContext.error.message;
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Error name (pulled from error type)
-***********************************************************************************************************************************/
 const char *
 errorName(void)
 {
     return errorTypeName(errorType());
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Error stack trace
-***********************************************************************************************************************************/
 const char *
 errorStackTrace(void)
 {
     return errorContext.error.stackTrace;
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Is this error an instance of the error type?
-***********************************************************************************************************************************/
 bool
 errorInstanceOf(const ErrorType *errorTypeTest)
 {
@@ -260,18 +230,14 @@ errorInternalState(void)
     return errorContext.tryList[errorContext.tryTotal].state;
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-True when in try state
-***********************************************************************************************************************************/
 bool
 errorInternalStateTry(void)
 {
     return errorInternalState() == errorStateTry;
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-True when in catch state and the expected error matches
-***********************************************************************************************************************************/
 bool
 errorInternalStateCatch(const ErrorType *errorTypeCatch)
 {
@@ -281,27 +247,21 @@ errorInternalStateCatch(const ErrorType *errorTypeCatch)
     return false;
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-True when in final state
-***********************************************************************************************************************************/
 bool
 errorInternalStateFinal(void)
 {
     return errorInternalState() == errorStateFinal;
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Return jump buffer for current try
-***********************************************************************************************************************************/
 jmp_buf *
 errorInternalJump(void)
 {
     return &errorContext.jumpList[errorContext.tryTotal - 1];
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Begin the try block
-***********************************************************************************************************************************/
 bool
 errorInternalTry(const char *fileName, const char *functionName, int fileLine)
 {
@@ -320,9 +280,7 @@ errorInternalTry(const char *fileName, const char *functionName, int fileLine)
     return true;
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Propagate the error up so it can be caught
-***********************************************************************************************************************************/
 void
 errorInternalPropagate(void)
 {
@@ -341,9 +299,7 @@ errorInternalPropagate(void)
     exit(UnhandledError.code);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Process the error through each try and state
-***********************************************************************************************************************************/
 bool
 errorInternalProcess(bool catch)
 {
@@ -385,9 +341,7 @@ errorInternalProcess(bool catch)
     return false;
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Throw an error
-***********************************************************************************************************************************/
 void
 errorInternalThrow(const ErrorType *errorType, const char *fileName, const char *functionName, int fileLine, const char *message)
 {
@@ -429,9 +383,7 @@ errorInternalThrowFmt(
     errorInternalThrow(errorType, fileName, functionName, fileLine, messageBufferTemp);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Throw a system error
-***********************************************************************************************************************************/
 void
 errorInternalThrowSys(
 #ifdef DEBUG_COVERAGE

src/common/error.h

@@ -61,28 +61,55 @@ typedef struct ErrorType ErrorType;
 /***********************************************************************************************************************************
 Functions to get information about a generic error type
 ***********************************************************************************************************************************/
+// Error type code
 int errorTypeCode(const ErrorType *errorType);
+
+// Get error type using a code
 const ErrorType *errorTypeFromCode(int code);
+
+// Error type name
 const char *errorTypeName(const ErrorType *errorType);
+
+// Error type parent
 const ErrorType *errorTypeParent(const ErrorType *errorType);
+
+// Does the child error type extend the parent error type?
 bool errorTypeExtends(const ErrorType *child, const ErrorType *parent);
 
 /***********************************************************************************************************************************
 Functions to get information about the current error
 ***********************************************************************************************************************************/
+// Error type
 const ErrorType *errorType(void);
+
+// Error code (pulled from error type)
 int errorCode(void);
+
+// Error filename
 const char *errorFileName(void);
+
+// Error function name
 const char *errorFunctionName(void);
+
+// Error file line number
 int errorFileLine(void);
+
+// Is this error an instance of the error type?
 bool errorInstanceOf(const ErrorType *errorTypeTest);
+
+// Error message
 const char *errorMessage(void);
+
+// Error name (pulled from error type)
 const char *errorName(void);
+
+// Error stack trace
 const char *errorStackTrace(void);
 
 /***********************************************************************************************************************************
 Functions to get information about the try stack
 ***********************************************************************************************************************************/
+// Get the depth of the current try statement (0 if none)
 unsigned int errorTryDepth(void);
 
 /***********************************************************************************************************************************
@@ -233,13 +260,28 @@ Internal functions
 
 These functions are used by the macros to implement the error handler and should never be called independently.
 ***********************************************************************************************************************************/
+// Begin the try block
 bool errorInternalTry(const char *fileName, const char *functionName, int fileLine);
+
+// Return jump buffer for current try
 jmp_buf *errorInternalJump(void);
+
+// True when in try state
 bool errorInternalStateTry(void);
+
+// True when in catch state and the expected error matches
 bool errorInternalStateCatch(const ErrorType *errorTypeCatch);
+
+// True when in final state
 bool errorInternalStateFinal(void);
+
+// Process the error through each try and state
 bool errorInternalProcess(bool catch);
+
+// Propagate the error up so it can be caught
 void errorInternalPropagate(void) __attribute__((__noreturn__));
+
+// Throw an error
 void errorInternalThrow(
     const ErrorType *errorType, const char *fileName, const char *functionName, int fileLine, const char *message)
     __attribute__((__noreturn__));
@@ -247,6 +289,7 @@ void errorInternalThrowFmt(
     const ErrorType *errorType, const char *fileName, const char *functionName, int fileLine, const char *format, ...)
     __attribute__((format(printf, 5, 6))) __attribute__((__noreturn__));
 
+// Throw a system error
 void errorInternalThrowSys(
 #ifdef DEBUG_COVERAGE
     bool error,

src/common/exec.c

@@ -105,9 +105,7 @@ OBJECT_DEFINE_FREE_RESOURCE_BEGIN(EXEC, LOG, logLevelTrace)
 }
 OBJECT_DEFINE_FREE_RESOURCE_END(LOG);
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-New object
-***********************************************************************************************************************************/
 Exec *
 execNew(const String *command, const StringList *param, const String *name, TimeMSec timeout)
 {
@@ -296,9 +294,7 @@ execHandleRead(const THIS_VOID)
     FUNCTION_TEST_RETURN(this->handleRead);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Execute command
-***********************************************************************************************************************************/
 void
 execOpen(Exec *this)
 {
@@ -372,9 +368,7 @@ execOpen(Exec *this)
     FUNCTION_LOG_RETURN_VOID();
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Get read interface
-***********************************************************************************************************************************/
 IoRead *
 execIoRead(const Exec *this)
 {
@@ -387,9 +381,7 @@ execIoRead(const Exec *this)
     FUNCTION_TEST_RETURN(this->ioReadExec);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Get write interface
-***********************************************************************************************************************************/
 IoWrite *
 execIoWrite(const Exec *this)
 {
@@ -402,9 +394,7 @@ execIoWrite(const Exec *this)
     FUNCTION_TEST_RETURN(this->ioWriteExec);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Get the object mem context
-***********************************************************************************************************************************/
 MemContext *
 execMemContext(const Exec *this)
 {

src/common/exec.h

@@ -29,13 +29,19 @@ Exec *execNew(const String *command, const StringList *param, const String *name
 /***********************************************************************************************************************************
 Functions
 ***********************************************************************************************************************************/
+// Execute command
 void execOpen(Exec *this);
 
 /***********************************************************************************************************************************
 Getters
 ***********************************************************************************************************************************/
+// Read interface
 IoRead *execIoRead(const Exec *this);
+
+// Write interface
 IoWrite *execIoWrite(const Exec *this);
+
+// Exec MemContext
 MemContext *execMemContext(const Exec *this);
 
 /***********************************************************************************************************************************

src/common/exit.c

@@ -69,9 +69,7 @@ exitOnSignal(int signalType)
     FUNCTION_LOG_RETURN_VOID();
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Setup signal handlers
-***********************************************************************************************************************************/
 void
 exitInit(void)
 {
@@ -87,9 +85,7 @@ exitInit(void)
     FUNCTION_LOG_RETURN_VOID();
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Do cleanup and return result code
-***********************************************************************************************************************************/
 int
 exitSafe(int result, bool error, SignalType signalType)
 {

src/common/exit.h

@@ -20,7 +20,10 @@ typedef enum
 /***********************************************************************************************************************************
 Functions
 ***********************************************************************************************************************************/
+// Setup signal handlers
 void exitInit(void);
+
+// Do cleanup and return result code
 int exitSafe(int result, bool error, SignalType signalType);
 
 #endif

src/common/fork.c

@@ -11,9 +11,7 @@ Fork Handler
 #include "common/error.h"
 #include "common/log.h"
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Fork a new process and throw an error if it fails
-***********************************************************************************************************************************/
 int
 forkSafe(void)
 {
@@ -26,10 +24,7 @@ forkSafe(void)
     FUNCTION_LOG_RETURN(INT, result);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Detach a forked process so it can continue running after the parent process has exited.  This is not a typical daemon startup
-because the parent process may continue to run and perform work for some time.
-***********************************************************************************************************************************/
 void
 forkDetach(void)
 {

src/common/fork.h

@@ -7,7 +7,11 @@ Fork Handler
 /***********************************************************************************************************************************
 Functions
 ***********************************************************************************************************************************/
+// Fork a new process and throw an error if it fails
 int forkSafe(void);
+
+// Detach a forked process so it can continue running after the parent process has exited. This is not a typical daemon startup
+// because the parent process may continue to run and perform work for some time.
 void forkDetach(void);
 
 #endif

src/common/ini.c

@@ -26,9 +26,7 @@ struct Ini
 OBJECT_DEFINE_MOVE(INI);
 OBJECT_DEFINE_FREE(INI);
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Create a new Ini object
-***********************************************************************************************************************************/
 Ini *
 iniNew(void)
 {
@@ -84,9 +82,7 @@ iniGetInternal(const Ini *this, const String *section, const String *key, bool r
     FUNCTION_TEST_RETURN(result);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Get an ini value -- error if it does not exist
-***********************************************************************************************************************************/
 const String *
 iniGet(const Ini *this, const String *section, const String *key)
 {
@@ -106,9 +102,7 @@ iniGet(const Ini *this, const String *section, const String *key)
     FUNCTION_TEST_RETURN(varStr(result));
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Get an ini value -- if it does not exist then return specified default
-***********************************************************************************************************************************/
 const String *
 iniGetDefault(const Ini *this, const String *section, const String *key, const String *defaultValue)
 {
@@ -129,9 +123,7 @@ iniGetDefault(const Ini *this, const String *section, const String *key, const S
     FUNCTION_TEST_RETURN(result == NULL ? defaultValue : varStr(result));
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Internal function to get an ini value list
-***********************************************************************************************************************************/
 StringList *
 iniGetList(const Ini *this, const String *section, const String *key)
 {
@@ -151,9 +143,7 @@ iniGetList(const Ini *this, const String *section, const String *key)
     FUNCTION_TEST_RETURN(result == NULL ? NULL : strLstNewVarLst(varVarLst(result)));
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Internal function to get an ini value list
-***********************************************************************************************************************************/
 bool
 iniSectionKeyIsList(const Ini *this, const String *section, const String *key)
 {
@@ -173,9 +163,7 @@ iniSectionKeyIsList(const Ini *this, const String *section, const String *key)
     FUNCTION_TEST_RETURN(varType(result) == varTypeVariantList);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Get a list of keys for a section
-***********************************************************************************************************************************/
 StringList *
 iniSectionKeyList(const Ini *this, const String *section)
 {
@@ -208,9 +196,7 @@ iniSectionKeyList(const Ini *this, const String *section)
     FUNCTION_TEST_RETURN(result);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Get a list of sections
-***********************************************************************************************************************************/
 StringList *
 iniSectionList(const Ini *this)
 {
@@ -234,9 +220,7 @@ iniSectionList(const Ini *this)
     FUNCTION_TEST_RETURN(result);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Parse ini from a string
-***********************************************************************************************************************************/
 void
 iniParse(Ini *this, const String *content)
 {
@@ -313,9 +297,7 @@ iniParse(Ini *this, const String *content)
     FUNCTION_TEST_RETURN_VOID();
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Set an ini value
-***********************************************************************************************************************************/
 void
 iniSet(Ini *this, const String *section, const String *key, const String *value)
 {
@@ -346,9 +328,7 @@ iniSet(Ini *this, const String *section, const String *key, const String *value)
     FUNCTION_TEST_RETURN_VOID();
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Load an ini file and return data to a callback
-***********************************************************************************************************************************/
 void
 iniLoad(
     IoRead *read, void (*callbackFunction)(void *data, const String *section, const String *key, const String *value),

src/common/ini.h

@@ -24,21 +24,35 @@ Ini *iniNew(void);
 /***********************************************************************************************************************************
 Functions
 ***********************************************************************************************************************************/
+// Move to a new parent mem context
 Ini *iniMove(Ini *this, MemContext *parentNew);
+
+// Parse ini from a string
 void iniParse(Ini *this, const String *content);
+
+// Set an ini value
 void iniSet(Ini *this, const String *section, const String *key, const String *value);
 
 /***********************************************************************************************************************************
 Getters
 ***********************************************************************************************************************************/
+// Get an ini value -- error if it does not exist
 const String *iniGet(const Ini *this, const String *section, const String *key);
+
+// Get an ini value -- if it does not exist then return specified default
 const String *iniGetDefault(const Ini *this, const String *section, const String *key, const String *defaultValue);
+
+// Ini key list
 StringList *iniGetList(const Ini *this, const String *section, const String *key);
+
+// The key's value is a list
 bool iniSectionKeyIsList(const Ini *this, const String *section, const String *key);
+
+// List of keys for a section
 StringList *iniSectionKeyList(const Ini *this, const String *section);
+
+// List of sections
 StringList *iniSectionList(const Ini *this);
-String *iniFileName(const Ini *this);
-bool iniFileExists(const Ini *this);
 
 /***********************************************************************************************************************************
 Destructor
@@ -48,6 +62,7 @@ void iniFree(Ini *this);
 /***********************************************************************************************************************************
 Helper Functions
 ***********************************************************************************************************************************/
+// Load an ini file and return data to a callback
 void iniLoad(
     IoRead *read, void (*callbackFunction)(void *data, const String *section, const String *key, const String *value),
     void *callbackData);

src/common/io/bufferRead.c

@@ -84,9 +84,7 @@ ioBufferReadEof(THIS_VOID)
     FUNCTION_LOG_RETURN(BOOL, this->eof);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-New object
-***********************************************************************************************************************************/
 IoRead *
 ioBufferReadNew(const Buffer *buffer)
 {

src/common/io/bufferWrite.c

@@ -48,9 +48,7 @@ ioBufferWrite(THIS_VOID, const Buffer *buffer)
     FUNCTION_LOG_RETURN_VOID();
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-New object
-***********************************************************************************************************************************/
 IoWrite *
 ioBufferWriteNew(Buffer *buffer)
 {

src/common/io/filter/buffer.c

@@ -106,9 +106,7 @@ ioBufferInputSame(const THIS_VOID)
     FUNCTION_TEST_RETURN(this->inputSame);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-New object
-***********************************************************************************************************************************/
 IoFilter *
 ioBufferNew(void)
 {

src/common/io/filter/filter.c

@@ -27,8 +27,6 @@ OBJECT_DEFINE_MOVE(IO_FILTER);
 OBJECT_DEFINE_FREE(IO_FILTER);
 
 /***********************************************************************************************************************************
-New object
-
 Allocations will be in the memory context of the caller.
 ***********************************************************************************************************************************/
 IoFilter *
@@ -64,9 +62,7 @@ ioFilterNew(const String *type, void *driver, VariantList *paramList, IoFilterIn
     FUNCTION_LOG_RETURN(IO_FILTER, this);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Filter input only (a result is expected)
-***********************************************************************************************************************************/
 void
 ioFilterProcessIn(IoFilter *this, const Buffer *input)
 {
@@ -88,9 +84,7 @@ ioFilterProcessIn(IoFilter *this, const Buffer *input)
     FUNCTION_TEST_RETURN_VOID();
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Filter input and produce output
-***********************************************************************************************************************************/
 void
 ioFilterProcessInOut(IoFilter *this, const Buffer *input, Buffer *output)
 {
@@ -117,8 +111,6 @@ ioFilterProcessInOut(IoFilter *this, const Buffer *input, Buffer *output)
 }
 
 /***********************************************************************************************************************************
-Is the filter done?
-
 If done is not defined by the filter then check inputSame.  If inputSame is true then the filter is not done.  Even if the filter
 is done the interface will not report done until the interface is flushing.
 ***********************************************************************************************************************************/
@@ -139,9 +131,7 @@ ioFilterDone(const IoFilter *this)
     FUNCTION_TEST_RETURN(result);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Driver for the filter
-***********************************************************************************************************************************/
 void *
 ioFilterDriver(IoFilter *this)
 {
@@ -154,11 +144,7 @@ ioFilterDriver(IoFilter *this)
     FUNCTION_TEST_RETURN(this->driver);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Does the filter need the same input again?
-
-If the filter cannot get all its output into the output buffer then it may need access to the same input again.
-***********************************************************************************************************************************/
 bool
 ioFilterInputSame(const IoFilter *this)
 {
@@ -171,9 +157,7 @@ ioFilterInputSame(const IoFilter *this)
     FUNCTION_TEST_RETURN(this->interface.inputSame != NULL ? this->interface.inputSame(this->driver) : false);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Interface for the filter
-***********************************************************************************************************************************/
 const IoFilterInterface *
 ioFilterInterface(const IoFilter *this)
 {
@@ -186,11 +170,7 @@ ioFilterInterface(const IoFilter *this)
     FUNCTION_TEST_RETURN(&this->interface);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Does filter produce output?
-
-All In filters produce output.
-***********************************************************************************************************************************/
 bool
 ioFilterOutput(const IoFilter *this)
 {
@@ -203,9 +183,7 @@ ioFilterOutput(const IoFilter *this)
     FUNCTION_TEST_RETURN(this->interface.inOut != NULL);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-List of filter parameters
-***********************************************************************************************************************************/
 const VariantList *
 ioFilterParamList(const IoFilter *this)
 {
@@ -218,9 +196,7 @@ ioFilterParamList(const IoFilter *this)
     FUNCTION_TEST_RETURN(this->paramList);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Get filter result
-***********************************************************************************************************************************/
 Variant *
 ioFilterResult(const IoFilter *this)
 {
@@ -233,11 +209,7 @@ ioFilterResult(const IoFilter *this)
     FUNCTION_TEST_RETURN(this->interface.result ? this->interface.result(this->driver) : NULL);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Get filter type
-
-This name identifies the filter and is used when pulling results from the filter group.
-***********************************************************************************************************************************/
 const String *
 ioFilterType(const IoFilter *this)
 {
@@ -250,9 +222,7 @@ ioFilterType(const IoFilter *this)
     FUNCTION_TEST_RETURN(this->type);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Render as string for logging
-***********************************************************************************************************************************/
 String *
 ioFilterToLog(const IoFilter *this)
 {

src/common/io/filter/filter.h

@@ -25,7 +25,10 @@ typedef struct IoFilter IoFilter;
 /***********************************************************************************************************************************
 Getters
 ***********************************************************************************************************************************/
+// Get filter result
 Variant *ioFilterResult(const IoFilter *this);
+
+// Identifies the filter and is used when pulling results from the filter group
 const String *ioFilterType(const IoFilter *this);
 
 /***********************************************************************************************************************************

src/common/io/filter/filter.intern.h

@@ -57,18 +57,35 @@ IoFilter *ioFilterNew(const String *type, void *driver, VariantList *paramList,
 /***********************************************************************************************************************************
 Functions
 ***********************************************************************************************************************************/
+// Filter input only (a result is expected)
 void ioFilterProcessIn(IoFilter *this, const Buffer *input);
+
+// Filter input and produce output
 void ioFilterProcessInOut(IoFilter *this, const Buffer *input, Buffer *output);
+
+// Move filter to a new parent mem context
 IoFilter *ioFilterMove(IoFilter *this, MemContext *parentNew);
 
 /***********************************************************************************************************************************
 Getters
 ***********************************************************************************************************************************/
+// Is the filter done?
 bool ioFilterDone(const IoFilter *this);
+
+// Driver for the filter
 void *ioFilterDriver(IoFilter *this);
+
+// Does the filter need the same input again? If the filter cannot get all its output into the output buffer then it may need access
+// to the same input again.
 bool ioFilterInputSame(const IoFilter *this);
+
+// Interface for the filter
 const IoFilterInterface *ioFilterInterface(const IoFilter *this);
+
+// Does filter produce output? All In filters produce output.
 bool ioFilterOutput(const IoFilter *this);
+
+// List of filter parameters
 const VariantList *ioFilterParamList(const IoFilter *this);
 
 /***********************************************************************************************************************************

src/common/io/filter/group.c

@@ -55,9 +55,7 @@ struct IoFilterGroup
 
 OBJECT_DEFINE_FREE(IO_FILTER_GROUP);
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-New Object
-***********************************************************************************************************************************/
 IoFilterGroup *
 ioFilterGroupNew(void)
 {
@@ -81,9 +79,7 @@ ioFilterGroupNew(void)
     FUNCTION_LOG_RETURN(IO_FILTER_GROUP, this);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Add a filter
-***********************************************************************************************************************************/
 IoFilterGroup *
 ioFilterGroupAdd(IoFilterGroup *this, IoFilter *filter)
 {
@@ -106,9 +102,7 @@ ioFilterGroupAdd(IoFilterGroup *this, IoFilter *filter)
     FUNCTION_LOG_RETURN(IO_FILTER_GROUP, this);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Insert a filter before an index
-***********************************************************************************************************************************/
 IoFilterGroup *
 ioFilterGroupInsert(IoFilterGroup *this, unsigned int listIdx, IoFilter *filter)
 {
@@ -147,9 +141,7 @@ ioFilterGroupGet(const IoFilterGroup *this, unsigned int filterIdx)
     FUNCTION_TEST_RETURN((IoFilterData *)lstGet(this->filterList, filterIdx));
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Clear filters
-***********************************************************************************************************************************/
 IoFilterGroup *
 ioFilterGroupClear(IoFilterGroup *this)
 {
@@ -169,9 +161,7 @@ ioFilterGroupClear(IoFilterGroup *this)
 }
 
 /***********************************************************************************************************************************
-Open filter group
+Setup the filter group and allocate any required buffers
-
-Setup the filter group and allocate any required buffers.
 ***********************************************************************************************************************************/
 void
 ioFilterGroupOpen(IoFilterGroup *this)
@@ -233,9 +223,7 @@ ioFilterGroupOpen(IoFilterGroup *this)
     FUNCTION_LOG_RETURN_VOID();
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Process filters
-***********************************************************************************************************************************/
 void
 ioFilterGroupProcess(IoFilterGroup *this, const Buffer *input, Buffer *output)
 {
@@ -361,9 +349,7 @@ ioFilterGroupProcess(IoFilterGroup *this, const Buffer *input, Buffer *output)
     FUNCTION_LOG_RETURN_VOID();
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Close filter group and gather results
-***********************************************************************************************************************************/
 void
 ioFilterGroupClose(IoFilterGroup *this)
 {
@@ -403,9 +389,7 @@ ioFilterGroupClose(IoFilterGroup *this)
     FUNCTION_LOG_RETURN_VOID();
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Is the filter group done processing?
-***********************************************************************************************************************************/
 bool
 ioFilterGroupDone(const IoFilterGroup *this)
 {
@@ -419,11 +403,7 @@ ioFilterGroupDone(const IoFilterGroup *this)
     FUNCTION_TEST_RETURN(this->done);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Should the same input be passed again?
-
-A buffer of input can produce multiple buffers of output, e.g. when a file containing all zeroes is being decompressed.
-***********************************************************************************************************************************/
 bool
 ioFilterGroupInputSame(const IoFilterGroup *this)
 {
@@ -437,9 +417,7 @@ ioFilterGroupInputSame(const IoFilterGroup *this)
     FUNCTION_TEST_RETURN(this->inputSame);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Get all filters and parameters so they can be passed to a remote
-***********************************************************************************************************************************/
 Variant *
 ioFilterGroupParamAll(const IoFilterGroup *this)
 {
@@ -467,9 +445,7 @@ ioFilterGroupParamAll(const IoFilterGroup *this)
     FUNCTION_LOG_RETURN(VARIANT, varNewVarLst(result));
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Get filter results
-***********************************************************************************************************************************/
 const Variant *
 ioFilterGroupResult(const IoFilterGroup *this, const String *filterType)
 {
@@ -492,9 +468,7 @@ ioFilterGroupResult(const IoFilterGroup *this, const String *filterType)
     FUNCTION_LOG_RETURN_CONST(VARIANT, result);
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Get all filter results
-***********************************************************************************************************************************/
 const Variant *
 ioFilterGroupResultAll(const IoFilterGroup *this)
 {
@@ -508,9 +482,7 @@ ioFilterGroupResultAll(const IoFilterGroup *this)
     FUNCTION_LOG_RETURN_CONST(VARIANT, varNewKv(this->filterResult));
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Set all filter results
-***********************************************************************************************************************************/
 void
 ioFilterGroupResultAllSet(IoFilterGroup *this, const Variant *filterResult)
 {
@@ -532,9 +504,7 @@ ioFilterGroupResultAllSet(IoFilterGroup *this, const Variant *filterResult)
     FUNCTION_LOG_RETURN_VOID();
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Return total number of filters
-***********************************************************************************************************************************/
 unsigned int
 ioFilterGroupSize(const IoFilterGroup *this)
 {
@@ -545,9 +515,7 @@ ioFilterGroupSize(const IoFilterGroup *this)
     FUNCTION_TEST_RETURN(lstSize(this->filterList));
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-Render as string for logging
-***********************************************************************************************************************************/
 String *
 ioFilterGroupToLog(const IoFilterGroup *this)
 {

src/common/io/filter/group.h

@@ -29,22 +29,47 @@ IoFilterGroup *ioFilterGroupNew(void);
 /***********************************************************************************************************************************
 Functions
 ***********************************************************************************************************************************/
+// Add a filter
 IoFilterGroup *ioFilterGroupAdd(IoFilterGroup *this, IoFilter *filter);
+
+// Insert a filter before an index
 IoFilterGroup *ioFilterGroupInsert(IoFilterGroup *this, unsigned int listIdx, IoFilter *filter);
+
+// Clear filters
 IoFilterGroup *ioFilterGroupClear(IoFilterGroup *this);
+
+// Open filter group
 void ioFilterGroupOpen(IoFilterGroup *this);
+
+// Process filters
 void ioFilterGroupProcess(IoFilterGroup *this, const Buffer *input, Buffer *output);
+
+// Close filter group and gather results
 void ioFilterGroupClose(IoFilterGroup *this);
 
 /***********************************************************************************************************************************
 Getters
 ***********************************************************************************************************************************/
+// Is the filter group done processing?
 bool ioFilterGroupDone(const IoFilterGroup *this);
+
+// Should the same input be passed again? A buffer of input can produce multiple buffers of output, e.g. when a file containing all
+// zeroes is being decompressed.
 bool ioFilterGroupInputSame(const IoFilterGroup *this);
+
+// Get all filters and their parameters so they can be passed to a remote
 Variant *ioFilterGroupParamAll(const IoFilterGroup *this);
+
+// Get filter results
 const Variant *ioFilterGroupResult(const IoFilterGroup *this, const String *filterType);
+
+// Get all filter results
 const Variant *ioFilterGroupResultAll(const IoFilterGroup *this);
+
+// Set all filter results
 void ioFilterGroupResultAllSet(IoFilterGroup *this, const Variant *filterResult);
+
+// Return total number of filters
 unsigned int ioFilterGroupSize(const IoFilterGroup *this);
 
 /***********************************************************************************************************************************

src/common/io/filter/sink.c

@@ -52,9 +52,7 @@ ioSinkProcess(THIS_VOID, const Buffer *input, Buffer *output)
     FUNCTION_LOG_RETURN_VOID();
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-New object
-***********************************************************************************************************************************/
 IoFilter *
 ioSinkNew(void)
 {

src/common/io/filter/size.c

@@ -79,9 +79,7 @@ ioSizeResult(THIS_VOID)
     FUNCTION_LOG_RETURN(VARIANT, varNewUInt64(this->size));
 }
 
-/***********************************************************************************************************************************
+/**********************************************************************************************************************************/
-New object
-***********************************************************************************************************************************/
 IoFilter *
 ioSizeNew(void)
 {