i18n_set.h and .c:Add function descriptions and license header

2 files changed, 95 insertions, 0 deletions

diff --git a/src/i18n_set.c b/src/i18n_set.c
index a539752..af7e3b6 100644
--- a/src/i18n_set.c
+++ b/src/i18n_set.c
@@ -1,5 +1,33 @@
+/**
+ * upwgen generates random internationalized passwords
+ * Copyright (C) 2019  Aaron Ball <nullspoon@oper.io>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
 #include "i18n_set.h"
 
+
+/**
+ * i18n_set_new:
+ * Constructor for an i18n_set struct. Allocates in heap and must be freed
+ * using i18n_set_free. Based on the @type passed in, will pre-fill the set
+ * object.
+ *
+ * @type Type of i18n set to instantiate
+ *
+ * @return The instantiated i18n_set struct
+ */
 struct i18n_set* i18n_set_new(int type) {
   struct i18n_set* out = malloc(sizeof(struct i18n_set));
 
@@ -39,6 +67,18 @@ struct i18n_set* i18n_set_new(int type) {
 }
 
 
+/**
+ * i18n_set_add:
+ * Instantiates and appends an i18n_set struct to an existing one. Since
+ * i18n_sets can be linked lists, this appends to one.
+ * Note that if the i18n_set passed is already in a linked list, this function
+ * will traverse to the end of the list and append there.
+ *
+ * @set  Existing i18n_set to append
+ * @type Type of new i18n_set to instantiate and append
+ *
+ * @return Pointer to the newly added i18n_set struct
+ */
 struct i18n_set* i18n_set_add(struct i18n_set* set, int type) {
   struct i18n_set* cursor = set;
   if(!set)
@@ -52,6 +92,17 @@ struct i18n_set* i18n_set_add(struct i18n_set* set, int type) {
 }
 
 
+/**
+ * i18n_set_exists:
+ * Checks the provided i18n_set linked list if it contains the specified set
+ * type. If it does, returns a pointer to that struct, otherwise returns NULL.
+ *
+ * @set   Linked list in which to check for the existence of the specified type
+ * @type  Type to check for
+ *
+ * @return Pointer to the i18n_set instance with type matching @type, otherwise
+ *         NULL
+ */
 struct i18n_set* i18n_set_exists(struct i18n_set* set, int type) {
   while(set) {
     if(set->type == type)
@@ -62,6 +113,19 @@ struct i18n_set* i18n_set_exists(struct i18n_set* set, int type) {
 }
 
 
+/**
+ * i18n_set_rm_type:
+ * Traverses the provided i18n_set linked list, removing any instances matching
+ * type @type.
+ * Note that the return value of this function should always be used, as if the
+ * linked list starts with an object matching @type, the beginning of the
+ * linked list will need to be repointed.
+ *
+ * @set  Set to remove objects matching @type
+ * @type Type of i18n_set to remove from linked list
+ *
+ * @return Pointer to the beginning of the i18n_set linked list
+ */
 struct i18n_set* i18n_set_rm_type(struct i18n_set* set, int type) {
   struct i18n_set* cursor = set;
   struct i18n_set* prev = NULL;
@@ -84,6 +148,13 @@ struct i18n_set* i18n_set_rm_type(struct i18n_set* set, int type) {
 }
 
 
+/**
+ * i18n_set_dump:
+ * Traverses the provided i18n_set linked list and prints the contents of each
+ * to stdout, with some handy extra information. Useful for debugging.
+ *
+ * @set i18n_set to dump
+ */
 void i18n_set_dump(struct i18n_set* set) {
   struct i18n_set* cursor = set;
   unsigned int total = 0;
@@ -96,6 +167,13 @@ void i18n_set_dump(struct i18n_set* set) {
 }
 
 
+/**
+ * i18n_set_free:
+ * Destructor for i18n_set structs. Will completely traverse the linked list to
+ * the end, freeing each item.
+ *
+ * @set i18n_set linked list to be freed
+ */
 void i18n_set_free(struct i18n_set* set) {
   struct i18n_set* next = NULL;
 
diff --git a/src/i18n_set.h b/src/i18n_set.h
index ccdf2ed..77fd08f 100644
--- a/src/i18n_set.h
+++ b/src/i18n_set.h
@@ -1,3 +1,20 @@
+/**
+ * upwgen generates random internationalized passwords
+ * Copyright (C) 2019  Aaron Ball <nullspoon@oper.io>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
 #include <stdlib.h>
 #include "i18n_cat.h"