Move comments documenting functions from the function definitions (.c
files) to the function declarations (.h files).  This convention means
that any installed headers (which describe the public API) will
include API documentaiton.  (The .c files are never installed, so
users won't see the documentation of public APIs if the comments are
in the .c files, unless the comments are converted to Doxygen and the
Doxygen documentation is compiled and installed.)

This change is not comprehensive; there are still some functions that
are documented near the definition.
---
 lib/rpki/querySupport.c |   6 --
 lib/rpki/scmf.h         | 156 +++++++++++++++++++++++++++++++++++++++++++++++
 lib/rpki/sqcon.c        | 158 ------------------------------------------------
 3 files changed, 156 insertions(+), 164 deletions(-)

diff --git a/lib/rpki/querySupport.c b/lib/rpki/querySupport.c
index 32db50f..9f3d850 100644
--- a/lib/rpki/querySupport.c
+++ b/lib/rpki/querySupport.c
@@ -81,9 +81,6 @@ static int registerParent(
     return 0;
 }
 
-/*
- * check the validity via the db of the cert whose ski or localID is given
- */
 int checkValidity(
     char *ski,
     unsigned int localID,
@@ -757,9 +754,6 @@ static QueryField fields[] = {
      }
 };
 
-/*
- * look up particular query field in the list of all possible fields
- */
 QueryField *findField(
     char *name)
 {
diff --git a/lib/rpki/scmf.h b/lib/rpki/scmf.h
index 0ca7ee1..304868e 100644
--- a/lib/rpki/scmf.h
+++ b/lib/rpki/scmf.h
@@ -106,66 +106,154 @@ typedef int (
 #define SQLOK(s) (s == SQL_SUCCESS || s == SQL_SUCCESS_WITH_INFO)
 #endif
 
+/*
+ * Initialize a connection to the named DSN. Return a connection object on
+ * success and a negative error code on failure.
+ */
 extern scmcon *connectscm(
     char *dsnp,
     char *errmsg,
     int emlen);
+
+/*
+ * Create a new empty srch array
+ */
 extern scmsrcha *newsrchscm(
     char *name,
     int leen,
     int cleenn,
     int useWhereStr);
+
+/*
+ * add clause for testing the value of a flag to a where string
+ */
 extern void addFlagTest(
     char *whereStr,
     int flagVal,
     int isSet,
     int needAnd);
+
+/*
+ * Disconnect from a DSN and free all memory.
+ */
 extern void disconnectscm(
     scmcon * conp);
+
+/*
+ * Free all the memory in a search array
+ */
 extern void freesrchscm(
     scmsrcha * srch);
+
+/*
+ * Convert a hex string into a byte array. Allocates memory. The string must
+ * not begin with 0x or ^x.
+ */
 extern void *unhexify(
     int strnglen,
     char const * strng);
+
+/*
+ * Get the error message from a connection.
+ */
 extern char *geterrorscm(
     scmcon * conp);
+
+/*
+ * Get the name of the table that had an error.
+ */
 extern char *gettablescm(
     scmcon * conp);
+
+/*
+ * Convert a binary array into a hex string. Allocates memory.
+ */
 extern char *hexify(
     int bytelen,
     void const * bytes,
     int useox);
+
+/*
+ * Get the number of rows returned by a statement.
+ */
 extern int getrowsscm(
     scmcon * conp);
+
+/*
+ * Execute an SQL statement.
+ *
+ * Before calling statementscm: You must call newhstmt(conp) and verify its
+ * return value.
+ *
+ * After calling statementscm and using its statement handle: You must call
+ * pophstmt(conp).
+ */
 extern int statementscm(
     scmcon * conp,
     char *stm);
+
+/*
+ * Execute a SQL statement, ignoring any returned rows.
+ */
 extern int statementscm_no_data(
     scmcon * conp,
     char *stm);
+
+/*
+ * Create a database and grant the mysql default user the standard set of
+ * privileges for that database.
+ */
 extern int createdbscm(
     scmcon * conp,
     char *dbname,
     char *dbuser);
+
+/*
+ * Delete a database.
+ */
 extern int deletedbscm(
     scmcon * conp,
     char *dbname);
+
+/*
+ * Create all the tables listed in scmp. This assumes that the database has
+ * already been created through a call to createdbscm().
+ */
 extern int createalltablesscm(
     scmcon * conp,
     scm * scmp);
+
+/*
+ * Insert an entry into a database table.
+ */
 extern int insertscm(
     scmcon * conp,
     scmtab * tabp,
     scmkva * arr);
+
+/*
+ * Get the maximum of the specified id field of the given table.  If table is
+ * empty, then sets *ival to 0.
+ */
 extern int getmaxidscm(
     scm * scmp,
     scmcon * conp,
     char *field,
     scmtab * mtab,
     unsigned int *ival);
+
 extern int getuintscm(
     scmcon * conp,
     unsigned int *ival);
+
+/*
+ * This function searches in a database table for entries that match the
+ * stated search criteria.
+ *
+ * Note that searchscm can be call recursively, so that there can be more than
+ * one cursor open at a time. For this reason, searchscm() must create its own
+ * STMT and then destroy it when it is done.
+ */
 extern int searchscm(
     scmcon * conp,
     scmtab * tabp,
@@ -174,11 +262,48 @@ extern int searchscm(
     sqlvaluefunc valer,
     int what,
     char *orderp);
+
+/*
+ * Add a new column to a search array. Note that this function does not grow
+ * the size of the column array, so enough space must have already been
+ * allocated when the array was created.
+ */
 extern int addcolsrchscm(
     scmsrcha * srch,
     char *colname,
     int sqltype,
     unsigned valsize);
+
+/*
+ * This function performs a find-or-create operation for a specific id. It
+ * first searches in table "tab" with search criteria "srch". If the entry is
+ * found it returns the value of the id. If it isn't found then the max_id is
+ * looked up in the metadata table and incremented, a new entry is created in
+ * "tab" using the creation criteria "ins", and the max id in the metadata
+ * table is updated and returned.
+ *
+ * Since this is somewhat convoluted and contains several steps, consider an
+ * example.  Suppose I wish to find or create two directories in the directory
+ * table.  These directories are /path/to/somewhere and /path/to/elsewhere.  I
+ * want to get the directory ids for these directories in either case, e.g.
+ * whether they are already there or have to be created. If a new directory is
+ * created I also want the maximum directory id in the metadata table to be
+ * updated.
+ *
+ * Consider the following putative sequence.  I construct a search for
+ * "/path/to/somewhere" in the directory table. The first element of the
+ * search is the id. The search succeeds, and the id is returned. The metadata
+ * table is unchanged. Now I construct a second search for
+ * "/path/to/elsewhere". That search fails. So I fetch the maximum directory
+ * id from the metadata table and increment it. I then create an entry in the
+ * directory table with elements "/path/to/elsewhere" and that (incremented)
+ * id. I update the metadata table's value for the max directory id to the
+ * new, incremented id, and, finally, I return that new, incremented id.
+ *
+ * Certs, CRLs, ROAs and directories all have ids and their tables all have
+ * max ids in the metadata table and so all of them have to be managed using
+ * this (sadly prolix) function.
+ */
 extern int searchorcreatescm(
     scm * scmp,
     scmcon * conp,
@@ -186,15 +311,31 @@ extern int searchorcreatescm(
     scmsrcha * srch,
     scmkva * ins,
     unsigned int *idp);
+
+/*
+ * This function deletes entries in a database table that match the stated
+ * search criteria.
+ */
 extern int deletescm(
     scmcon * conp,
     scmtab * tabp,
     scmkva * deld);
+
+/*
+ * Set the flags value on a match corresponding to a search criterion.
+ *
+ * This function returns 0 on success and a negative error code on failure.
+ */
 extern int setflagsscm(
     scmcon * conp,
     scmtab * tabp,
     scmkva * where,
     unsigned int flags);
+
+/*
+ * This very specific function updates the sninuse and snlist entries on a CRL
+ * using the local_id as the where criterion.
+ */
 extern int updateblobscm(
     scmcon * conp,
     scmtab * tabp,
@@ -202,13 +343,28 @@ extern int updateblobscm(
     unsigned int sninuse,
     unsigned int snlen,
     unsigned int lid);
+
+/*
+ * This specialized function updates the appropriate xx_last field in the
+ * metadata table for the indicated time when the client completed.
+ */
 extern int updateranlastscm(
     scmcon * conp,
     scmtab * mtab,
     char what,
     char *now);
+
+/*
+ * Create a new STMT and push it onto the top of the stack of STMTs in the
+ * connection.
+ */
 extern SQLRETURN newhstmt(
     scmcon * conp);
+
+/*
+ * Pop the top element off the hstmt stack of a connection, free the hstmt and
+ * the associated memory.
+ */
 extern void pophstmt(
     scmcon * conp);
 
diff --git a/lib/rpki/sqcon.c b/lib/rpki/sqcon.c
index 1c5e0d0..9cc194d 100644
--- a/lib/rpki/sqcon.c
+++ b/lib/rpki/sqcon.c
@@ -54,10 +54,6 @@ static void freehstack(
     }
 }
 
-/*
- * Disconnect from a DSN and free all memory.
- */
-
 void disconnectscm(
     scmcon * conp)
 {
@@ -99,11 +95,6 @@ void disconnectscm(
  * SQL_IS_UINTEGER);
  */
 
-/*
- * Create a new STMT and push it onto the top of the stack of STMTs in the
- * connection.
- */
-
 SQLRETURN newhstmt(
     scmcon * conp)
 {
@@ -134,11 +125,6 @@ SQLRETURN newhstmt(
     return (0);
 }
 
-/*
- * Pop the top element off the hstmt stack of a connection, free the hstmt and
- * the associated memory.
- */
-
 void pophstmt(
     scmcon * conp)
 {
@@ -155,11 +141,6 @@ void pophstmt(
     free((void *)stackp);
 }
 
-/*
- * Initialize a connection to the named DSN. Return a connection object on
- * success and a negative error code on failure.
- */
-
 scmcon *connectscm(
     char *dsnp,
     char *errmsg,
@@ -259,10 +240,6 @@ scmcon *connectscm(
     return (conp);
 }
 
-/*
- * Get the error message from a connection.
- */
-
 char *geterrorscm(
     scmcon * conp)
 {
@@ -271,10 +248,6 @@ char *geterrorscm(
     return (conp->mystat.errmsg);
 }
 
-/*
- * Get the name of the table that had an error.
- */
-
 char *gettablescm(
     scmcon * conp)
 {
@@ -283,11 +256,6 @@ char *gettablescm(
     return (conp->mystat.tabname);
 }
 
-
-/*
- * Get the number of rows returned by a statement.
- */
-
 int getrowsscm(
     scmcon * conp)
 {
@@ -299,16 +267,6 @@ int getrowsscm(
     return (r);
 }
 
-/*
- * Execute an SQL statement.
- *
- * Before calling statementscm: You must call newhstmt(conp) and verify its
- * return value.
- *
- * After calling statementscm and using its statement handle: You must call
- * pophstmt(conp).
- */
-
 int statementscm(
     scmcon * conp,
     char *stm)
@@ -339,10 +297,6 @@ int statementscm(
     return (0);
 }
 
-/*
- * Execute a SQL statement, ignoring any returned rows.
- */
-
 int statementscm_no_data(
     scmcon * conp,
     char *stm)
@@ -360,12 +314,6 @@ int statementscm_no_data(
     return ret;
 }
 
-
-/*
- * Create a database and grant the mysql default user the standard set of
- * privileges for that database.
- */
-
 int createdbscm(
     scmcon * conp,
     char *dbname,
@@ -388,10 +336,6 @@ int createdbscm(
     return (sta);
 }
 
-/*
- * Delete a database.
- */
-
 int deletedbscm(
     scmcon * conp,
     char *dbname)
@@ -439,11 +383,6 @@ static int createonetablescm(
     return (sta);
 }
 
-/*
- * Create all the tables listed in scmp. This assumes that the database has
- * already been created through a call to createdbscm().
- */
-
 int createalltablesscm(
     scmcon * conp,
     scm * scmp)
@@ -596,11 +535,6 @@ static int quote_value(
     }
 }
 
-
-/*
- * Insert an entry into a database table.
- */
-
 int insertscm(
     scmcon * conp,
     scmtab * tabp,
@@ -725,11 +659,6 @@ int getuintscm(
         return (0);
 }
 
-/*
- * Get the maximum of the specified id field of the given table.  If table is
- * empty, then sets *ival to 0.
- */
-
 int getmaxidscm(
     scm * scmp,
     scmcon * conp,
@@ -794,15 +723,6 @@ static int validsrchscm(
     return (0);
 }
 
-/*
- * This function searches in a database table for entries that match the
- * stated search criteria.
- *
- * Note that searchscm can be call recursively, so that there can be more than
- * one cursor open at a time. For this reason, searchscm() must create its own
- * STMT and then destroy it when it is done.
- */
-
 int searchscm(
     scmcon * conp,
     scmtab * tabp,
@@ -1049,10 +969,6 @@ int searchscm(
         return (0);
 }
 
-/*
- * Free all the memory in a search array
- */
-
 void freesrchscm(
     scmsrcha * srch)
 {
@@ -1098,9 +1014,6 @@ void freesrchscm(
     }
 }
 
-/*
- * add clause for testing the value of a flag to a where string
- */
 void addFlagTest(
     char *whereStr,
     int flagVal,
@@ -1126,10 +1039,6 @@ void addFlagTest(
               flagVal);
 }
 
-/*
- * Create a new empty srch array
- */
-
 scmsrcha *newsrchscm(
     char *name,
     int leen,
@@ -1179,12 +1088,6 @@ scmsrcha *newsrchscm(
     return (newp);
 }
 
-/*
- * Add a new column to a search array. Note that this function does not grow
- * the size of the column array, so enough space must have already been
- * allocated when the array was created.
- */
-
 int addcolsrchscm(
     scmsrcha * srch,
     char *colname,
@@ -1237,37 +1140,6 @@ static int socvaluefunc(
     return (-1);
 }
 
-/*
- * This function performs a find-or-create operation for a specific id. It
- * first searches in table "tab" with search criteria "srch". If the entry is
- * found it returns the value of the id. If it isn't found then the max_id is
- * looked up in the metadata table and incremented, a new entry is created in
- * "tab" using the creation criteria "ins", and the max id in the metadata
- * table is updated and returned.
- *
- * Since this is somewhat convoluted and contains several steps, consider an
- * example.  Suppose I wish to find or create two directories in the directory
- * table.  These directories are /path/to/somewhere and /path/to/elsewhere.  I
- * want to get the directory ids for these directories in either case, e.g.
- * whether they are already there or have to be created. If a new directory is
- * created I also want the maximum directory id in the metadata table to be
- * updated.
- *
- * Consider the following putative sequence.  I construct a search for
- * "/path/to/somewhere" in the directory table. The first element of the
- * search is the id. The search succeeds, and the id is returned. The metadata
- * table is unchanged. Now I construct a second search for
- * "/path/to/elsewhere". That search fails. So I fetch the maximum directory
- * id from the metadata table and increment it. I then create an entry in the
- * directory table with elements "/path/to/elsewhere" and that (incremented)
- * id. I update the metadata table's value for the max directory id to the
- * new, incremented id, and, finally, I return that new, incremented id.
- *
- * Certs, CRLs, ROAs and directories all have ids and their tables all have
- * max ids in the metadata table and so all of them have to be managed using
- * this (sadly prolix) function.
- */
-
 int searchorcreatescm(
     scm * scmp,
     scmcon * conp,
@@ -1325,11 +1197,6 @@ int searchorcreatescm(
     return (0);
 }
 
-/*
- * This function deletes entries in a database table that match the stated
- * search criteria.
- */
-
 int deletescm(
     scmcon * conp,
     scmtab * tabp,
@@ -1413,12 +1280,6 @@ int deletescm(
     return (sta);
 }
 
-/*
- * Set the flags value on a match corresponding to a search criterion.
- *
- * This function returns 0 on success and a negative error code on failure.
- */
-
 int setflagsscm(
     scmcon * conp,
     scmtab * tabp,
@@ -1482,10 +1343,6 @@ int setflagsscm(
     return (sta);
 }
 
-/*
- * Convert a binary array into a hex string. Allocates memory.
- */
-
 char *hexify(
     int bytelen,
     void const * ptr,
@@ -1536,11 +1393,6 @@ char *hexify(
     return (aptr);
 }
 
-/*
- * Convert a hex string into a byte array. Allocates memory. The string must
- * not begin with 0x or ^x.
- */
-
 void *unhexify(
     int strnglen,
     char const * strng)
@@ -1575,11 +1427,6 @@ void *unhexify(
     return oot;
 }
 
-/*
- * This very specific function updates the sninuse and snlist entries on a CRL
- * using the local_id as the where criterion.
- */
-
 int updateblobscm(
     scmcon * conp,
     scmtab * tabp,
@@ -1613,11 +1460,6 @@ int updateblobscm(
     return (sta);
 }
 
-/*
- * This specialized function updates the appropriate xx_last field in the
- * metadata table for the indicated time when the client completed.
- */
-
 int updateranlastscm(
     scmcon * conp,
     scmtab * mtab,
-- 
2.4.5


------------------------------------------------------------------------------
Don't Limit Your Business. Reach for the Cloud.
GigeNET's Cloud Solutions provide you with the tools and support that
you need to offload your IT needs and focus on growing your business.
Configured For All Businesses. Start Your Cloud Today.
https://www.gigenetcloud.com/
_______________________________________________
rpstir-devel mailing list
rpstir-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/rpstir-devel

Reply via email to