Add a bunch of docstrings

1 files changed, 17 insertions, 3 deletions

diff --git a/src/main.c b/src/main.c
index 6abe608..932bbb3 100644
--- a/src/main.c
+++ b/src/main.c
@@ -12,8 +12,12 @@
 
 #define DATABASE_PATH (FTAG_ROOT "/ftag.sqlite3")
 
+/* Structure that aims at making parsing commands and sub-commands options
+ * easy. The work is done by the parse_args function. */
 struct ftag_command {
 	const char *name;
+	/* Execute the command, eventually by parsing some options. FUNC may
+	 * shift ARGC and ARGV and call parse_args again. */
 	void (*func)(int argc, char **argv);
 };
 
@@ -67,12 +71,15 @@ static void assert_db_exists(void)
 /* Make sure STR contains no single quote, not to break SQL queries. */
 static void assert_no_single_quote(const char *str)
 {
+	/* TODO: perform fancy backslash insertion */
 	assert(strchr(str, '\'') == NULL);
 	assert(strchr(str, ';') == NULL);
 }
 
+/* Write an id to *_ID, used by table_next_id. Write 0 if no id is found. */
 static int table_next_id_callback(void *_id, int, char **cols, char **)
 {
+	/* output has only one column, so our id is in COLS[0] */
 	int *id = _id;
 	if (cols[0])
 		*id = atoi(cols[0]);
@@ -81,9 +88,10 @@ static int table_next_id_callback(void *_id, int, char **cols, char **)
 	return 0;
 }
 
+/* Get the next id for inserting a row in TABLE. */
 static int table_next_id(sqlite3 *db, const char *table)
 {
-	int last_id = -1;
+	int last_id = -1; /* last ID _currently used_ in the table */
 	int rc;
 	char sql[128];
 	memset(sql, 0, sizeof(sql));
@@ -95,6 +103,7 @@ static int table_next_id(sqlite3 *db, const char *table)
 	return last_id + 1;
 }
 
+/* Create ftag's database and directories. */
 static void ftag_init(int, char **)
 {
 	int rc = mkdir(FTAG_ROOT "/files", 0755);
@@ -111,6 +120,7 @@ static void ftag_init(int, char **)
 	exit(EXIT_FAILURE);
 }
 
+/* Sqlite callback that prints the first column without header. */
 static int ftag_print(void *, int, char **cols, char **)
 {
 	assert(cols[0]);
@@ -132,8 +142,8 @@ static void ftag_list_table(const char *table, const char *col)
 	sqlite3_close(db);
 }
 
-/* Write to OUT a version of IN that does not contain any blank or uppercase
- * letter. */
+/* Write to OUT a version of IN that does not contain any whitespace character
+ * or uppercase letter. */
 static void canonicalize(char *out, const char *in)
 {
 	int i;
@@ -148,6 +158,7 @@ static void canonicalize(char *out, const char *in)
 	out[i] = '\0';
 }
 
+/* Add a new file to the databse, prompting the user for needed information. */
 static void ftag_add_one_file(sqlite3 *db,
 			      int *next_id,
 			      const char *file)
@@ -303,6 +314,8 @@ static int get_id_by_col_callback(void *_id, int, char **cols, char **)
 	}
 }
 
+/* Write to *_ID the id of the entry of TABLE that has the value VAL for column
+ * COL. */
 static int get_id_by_col(sqlite3 *db,
 			 const char *table,
 			 const char *col,
@@ -376,6 +389,7 @@ static void ftag_query_usage(void)
 	fprintf(stderr, "usage: ftag query [-a DATE] [-b DATE] [-t TAG]...\n");
 }
 
+/* Debugging callback that prints all the output. */
 static int print_all_callback(void *_print_header, int count, char **cols, char **col_names)
 {
 	int *print_header = _print_header;