Improve documentation (#48)

Author: bkthomps

src/array.c

@@ -37,7 +37,9 @@ struct internal_array {
  *                      negative
  * @param data_size     the size of each element in the array; must be positive
  *
- * @return the newly-initialized array, or NULL if memory allocation error
+ * @return the newly-initialized array, or NULL if it was not successfully
+ *         initialized due to either invalid input arguments or memory
+ *         allocation error
  */
 array array_init(const int element_count, const size_t data_size)
 {
@@ -76,7 +78,10 @@ int array_size(array me)
 }
 
 /**
- * Copies the array to a raw array.
+ * Copies the array to a raw array. Since it is a copy, the raw array may be
+ * modified without causing side effects to the array data structure. Memory
+ * is not allocated, thus the raw array being used for the copy must be
+ * allocated before this function is called.
  *
  * @param arr the initialized raw array to copy the array to
  * @param me  the array to copy to the raw array
@@ -90,10 +95,10 @@ void array_copy_to_array(void *const arr, array me)
 }
 
 /**
- * Gets the storage element of the array which is contiguous in memory. If the
- * data is modified, the data in the array is modified. Also, any array
- * operation may invalidate this data pointer. The array owns the data pointer,
- * thus it must not be freed.
+ * Gets the storage element of the array structure. This pointer is not a copy,
+ * thus any modification to the data will cause the array structure data to be
+ * modified. Operations using the array functions may invalidate this pointer.
+ * The array owns this memory, thus it should not be freed.
  *
  * @param me the array to get the storage element from
  *
@@ -113,7 +118,11 @@ static int array_is_illegal_input(array me, const int index)
 }
 
 /**
- * Sets the data for a specified element in the array.
+ * Sets the data for a specified element in the array. The pointer to the data
+ * being passed in should point to the data type which this array holds. For
+ * example, if this array holds integers, the data pointer should be a pointer
+ * to an integer. Since the data is being copied, the pointer only has to be
+ * valid when this function is called.
  *
  * @param me    the array to set data for
  * @param index the location to set data at in the array
@@ -133,7 +142,12 @@ int array_set(array me, const int index, void *const data)
 }
 
 /**
- * Copies the element at index of the array to data.
+ * Copies the element at index of the array to data. The pointer to the data
+ * being obtained should point to the data type which this array holds. For
+ * example, if this array holds integers, the data pointer should be a pointer
+ * to an integer. Since this data is being copied from the array to the data
+ * pointer, the pointer only has to be valid when this function is called.
+ *
  *
  * @param data  the data to copy to
  * @param me    the array to copy from

src/deque.c

@@ -44,7 +44,9 @@ struct node {
  *
  * @param data_size the size of each element in the deque; must be positive
  *
- * @return the newly-initialized deque, or NULL if memory allocation error
+ * @return the newly-initialized deque, or NULL if it was not successfully
+ *         initialized due to either invalid input arguments or memory
+ *         allocation error
  */
 deque deque_init(const size_t data_size)
 {
@@ -145,7 +147,10 @@ int deque_trim(deque me)
 }
 
 /**
- * Copies the deque to an array.
+ * Copies the deque to an array. Since it is a copy, the array may be modified
+ * without causing side effects to the deque data structure. Memory is not
+ * allocated, thus the array being used for the copy must be allocated before
+ * this function is called.
  *
  * @param arr the initialized array to copy the deque to
  * @param me  the deque to copy to the array
@@ -159,7 +164,11 @@ void deque_copy_to_array(void *const arr, deque me)
 }
 
 /**
- * Adds an element to the front of the deque.
+ * Adds an element to the front of the deque. The pointer to the data being
+ * passed in should point to the data type which this deque holds. For example,
+ * if this deque holds integers, the data pointer should be a pointer to an
+ * integer. Since the data is being copied, the pointer only has to be valid
+ * when this function is called.
  *
  * @param me   the deque to add an element to
  * @param data the element to add
@@ -221,7 +230,11 @@ int deque_push_front(deque me, void *const data)
 }
 
 /**
- * Adds an element to the back of the deque.
+ * Adds an element to the back of the deque. The pointer to the data being
+ * passed in should point to the data type which this deque holds. For example,
+ * if this deque holds integers, the data pointer should be a pointer to an
+ * integer. Since the data is being copied, the pointer only has to be valid
+ * when this function is called.
  *
  * @param me   the deque to add an element to
  * @param data the element to add
@@ -268,7 +281,12 @@ int deque_push_back(deque me, void *const data)
 }
 
 /**
- * Removes the front element from the deque and copies it to a data value.
+ * Removes the front element from the deque and copies it to a data value. The
+ * pointer to the data being obtained should point to the data type which this
+ * deque holds. For example, if this deque holds integers, the data pointer
+ * should be a pointer to an integer. Since this data is being copied from the
+ * array to the data pointer, the pointer only has to be valid when this
+ * function is called.
  *
  * @param data the value to copy to
  * @param me   the deque to remove from
@@ -294,7 +312,12 @@ int deque_pop_front(void *const data, deque me)
 }
 
 /**
- * Removes the back element from the deque and copies it to a data value.
+ * Removes the back element from the deque and copies it to a data value. The
+ * pointer to the data being obtained should point to the data type which this
+ * deque holds. For example, if this deque holds integers, the data pointer
+ * should be a pointer to an integer. Since this data is being copied from the
+ * array to the data pointer, the pointer only has to be valid when this
+ * function is called.
  *
  * @param data the value to copy to
  * @param me   the deque to remove from
@@ -320,7 +343,11 @@ int deque_pop_back(void *const data, deque me)
 }
 
 /**
- * Sets the first value of the deque.
+ * Sets the first value of the deque. The pointer to the data being passed in
+ * should point to the data type which this deque holds. For example, if this
+ * deque holds integers, the data pointer should be a pointer to an integer.
+ * Since the data is being copied, the pointer only has to be valid when this
+ * function is called.
  *
  * @param me   the deque to set value of
  * @param data the data to set
@@ -334,7 +361,11 @@ int deque_set_first(deque me, void *const data)
 }
 
 /**
- * Sets the value of the deque at the specified index.
+ * Sets the value of the deque at the specified index. The pointer to the data
+ * being passed in should point to the data type which this deque holds. For
+ * example, if this deque holds integers, the data pointer should be a pointer
+ * to an integer. Since the data is being copied, the pointer only has to be
+ * valid when this function is called.
  *
  * @param me    the deque to set value of
  * @param index the index to set at
@@ -361,7 +392,11 @@ int deque_set_at(deque me, int index, void *const data)
 }
 
 /**
- * Sets the last value of the deque.
+ * Sets the last value of the deque. The pointer to the data being passed in
+ * should point to the data type which this deque holds. For example, if this
+ * deque holds integers, the data pointer should be a pointer to an integer.
+ * Since the data is being copied, the pointer only has to be valid when this
+ * function is called.
  *
  * @param me   the deque to set value of
  * @param data the data to set
@@ -375,7 +410,11 @@ int deque_set_last(deque me, void *const data)
 }
 
 /**
- * Gets the first value of the deque.
+ * Gets the first value of the deque. The pointer to the data being obtained
+ * should point to the data type which this deque holds. For example, if this
+ * deque holds integers, the data pointer should be a pointer to an integer.
+ * Since this data is being copied from the array to the data pointer, the
+ * pointer only has to be valid when this function is called.
  *
  * @param data the data to set
  * @param me   the deque to set value of
@@ -389,7 +428,11 @@ int deque_get_first(void *const data, deque me)
 }
 
 /**
- * Gets the value of the deque at the specified index.
+ * Gets the value of the deque at the specified index. The pointer to the data
+ * being obtained should point to the data type which this deque holds. For
+ * example, if this deque holds integers, the data pointer should be a pointer
+ * to an integer. Since this data is being copied from the array to the data
+ * pointer, the pointer only has to be valid when this function is called.
  *
  * @param data  the data to set
  * @param me    the deque to set value of
@@ -416,7 +459,11 @@ int deque_get_at(void *const data, deque me, int index)
 }
 
 /**
- * Gets the last value of the deque.
+ * Gets the last value of the deque. The pointer to the data being obtained
+ * should point to the data type which this deque holds. For example, if this
+ * deque holds integers, the data pointer should be a pointer to an integer.
+ * Since this data is being copied from the array to the data pointer, the
+ * pointer only has to be valid when this function is called.
  *
  * @param data the data to set
  * @param me   the deque to set value of

src/forward_list.c

@@ -40,8 +40,9 @@ struct node {
  *
  * @param data_size the size of data to store; must be positive
  *
- * @return the newly-initialized singly-linked list, or NULL if memory
- *         allocation error
+ * @return the newly-initialized singly-linked list, or NULL if it was not
+ *         successfully initialized due to either invalid input arguments or
+ *         memory allocation error
  */
 forward_list forward_list_init(const size_t data_size)
 {
@@ -84,7 +85,10 @@ int forward_list_is_empty(forward_list me)
 }
 
 /**
- * Copies the nodes of the singly-linked list to an array.
+ * Copies the nodes of the singly-linked list to an array. Since it is a copy,
+ * the array may be modified without causing side effects to the singly-linked
+ * list data structure. Memory is not allocated, thus the array being used for
+ * the copy must be allocated before this function is called.
  *
  * @param arr the initialized array to copy the singly-linked list to
  * @param me  the singly-linked list to copy to the array
@@ -114,7 +118,11 @@ static struct node *forward_list_get_node_at(forward_list me, const int index)
 }
 
 /**
- * Adds data at the first index in the singly-linked list.
+ * Adds data at the first index in the singly-linked list. The pointer to the
+ * data being passed in should point to the data type which this singly-linked
+ * list holds. For example, if this singly-linked list holds integers, the data
+ * pointer should be a pointer to an integer. Since the data is being copied,
+ * the pointer only has to be valid when this function is called.
  *
  * @param me   the singly-linked list to add data to
  * @param data the data to add to the singly-linked list
@@ -128,7 +136,11 @@ int forward_list_add_first(forward_list me, void *const data)
 }
 
 /**
- * Adds data at a specified index in the singly-linked list.
+ * Adds data at a specified index in the singly-linked list. The pointer to the
+ * data being passed in should point to the data type which this singly-linked
+ * list holds. For example, if this singly-linked list holds integers, the data
+ * pointer should be a pointer to an integer. Since the data is being copied,
+ * the pointer only has to be valid when this function is called.
  *
  * @param me    the singly-linked list to add data to
  * @param index the index to add the data at
@@ -167,7 +179,11 @@ int forward_list_add_at(forward_list me, const int index, void *const data)
 }
 
 /**
- * Adds data at the last index in the singly-linked list.
+ * Adds data at the last index in the singly-linked list. The pointer to the
+ * data being passed in should point to the data type which this singly-linked
+ * list holds. For example, if this singly-linked list holds integers, the data
+ * pointer should be a pointer to an integer. Since the data is being copied,
+ * the pointer only has to be valid when this function is called.
  *
  * @param me   the singly-linked list to add data to
  * @param data the data to add to the singly-linked list
@@ -250,7 +266,11 @@ int forward_list_remove_last(forward_list me)
 }
 
 /**
- * Sets the data at the first index in the singly-linked list.
+ * Sets the data at the first index in the singly-linked list. The pointer to
+ * the data being passed in should point to the data type which this singly-
+ * linked list holds. For example, if this singly-linked list holds integers,
+ * the data pointer should be a pointer to an integer. Since the data is being
+ * copied, the pointer only has to be valid when this function is called.
  *
  * @param me   the singly-linked list to set data for
  * @param data the data to set in the singly-linked list
@@ -264,7 +284,11 @@ int forward_list_set_first(forward_list me, void *const data)
 }
 
 /**
- * Sets the data at the specified index in the singly-linked list.
+ * Sets the data at the specified index in the singly-linked list. The pointer
+ * to the data being passed in should point to the data type which this singly-
+ * linked list holds. For example, if this singly-linked list holds integers,
+ * the data pointer should be a pointer to an integer. Since the data is being
+ * copied, the pointer only has to be valid when this function is called.
  *
  * @param me    the singly-linked list to set data for
  * @param index the index to set data in the singly-linked list
@@ -285,7 +309,11 @@ int forward_list_set_at(forward_list me, const int index, void *const data)
 }
 
 /**
- * Sets the data at the last index in the singly-linked list.
+ * Sets the data at the last index in the singly-linked list. The pointer to
+ * the data being passed in should point to the data type which this singly-
+ * linked list holds. For example, if this singly-linked list holds integers,
+ * the data pointer should be a pointer to an integer. Since the data is being
+ * copied, the pointer only has to be valid when this function is called.
  *
  * @param me   the singly-linked list to set data for
  * @param data the data to set in the singly-linked list
@@ -299,7 +327,12 @@ int forward_list_set_last(forward_list me, void *const data)
 }
 
 /**
- * Gets the data at the first index in the singly-linked list.
+ * Gets the data at the first index in the singly-linked list. The pointer to
+ * the data being obtained should point to the data type which this singly-
+ * linked list holds. For example, if this singly-linked list holds integers,
+ * the data pointer should be a pointer to an integer. Since this data is being
+ * copied from the array to the data pointer, the pointer only has to be valid
+ * when this function is called.
  *
  * @param data the data to get
  * @param me   the singly-linked list to get data from
@@ -313,7 +346,12 @@ int forward_list_get_first(void *const data, forward_list me)
 }
 
 /**
- * Gets the data at the specified index in the singly-linked list.
+ * Gets the data at the specified index in the singly-linked list. The pointer
+ * to the data being obtained should point to the data type which this singly-
+ * linked list holds. For example, if this singly-linked list holds integers,
+ * the data pointer should be a pointer to an integer. Since this data is being
+ * copied from the array to the data pointer, the pointer only has to be valid
+ * when this function is called.
  *
  * @param data  the data to get
  * @param me    the singly-linked list to get data from
@@ -334,7 +372,12 @@ int forward_list_get_at(void *const data, forward_list me, const int index)
 }
 
 /**
- * Gets the data at the last index in the singly-linked list.
+ * Gets the data at the last index in the singly-linked list. The pointer to
+ * the data being obtained should point to the data type which this singly-
+ * linked list holds. For example, if this singly-linked list holds integers,
+ * the data pointer should be a pointer to an integer. Since this data is being
+ * copied from the array to the data pointer, the pointer only has to be valid
+ * when this function is called.
  *
  * @param data the data to get
  * @param me   the singly-linked list to get data from