Add remaining documentation

[libcontrac.git] / src / dtk_list.c

diff --git a/src/dtk_list.c b/src/dtk_list.c
index daa03d0..f7ab67b 100644 (file)
--- a/src/dtk_list.c
+++ b/src/dtk_list.c
@@ -1,17 +1,25 @@
-/** \ingroup contrac
+/** \ingroup KeyGeneration
  * @file
- * @author     David Llewellyn-Jones
+ * @author     David Llewellyn-Jones <david@flypig.co.uk>
  * @version    $(VERSION)
  *
  * @section LICENSE
  *
+ * Copyright David Llewellyn-Jones, 2020
+ * Released under the GPLv2.
  *
- *
- * @brief
+ * @brief Provides a list of DTKs 
  * @section DESCRIPTION
  *
+ * This class allows the simplified management of lists of Dtk objects. This is
+ * useful when checking DTKs received from a Diagnosis Server with RPIs
+ * captured over Bluetooth. Combined with the \ref RpiList class the two can
+ * be easily stored and passed into the \ref match_list_find_matches() function.
  *
- *
+ */
+
+/** \addtogroup Containers
+ *  @{
  */
 
 // Includes
@@ -31,11 +39,30 @@
 
 // Structures
 
+/**
+ * @brief A DTK list element
+ *
+ * This is an opaque structure that represents a single item in the list and
+ * contains a Dtk instance.
+ * 
+ * The structure typedef is in dtk_list.h
+ */
 struct _DtkListItem {
        Dtk * dtk;
        DtkListItem * next;
 };
 
+/**
+ * @brief The head of a DTK list
+ *
+ * This is an opaque structure that represents the head of a list of Dtk
+ * items.
+ * 
+ * This is the object usually passed as the first parameter of every non-static
+ * function.
+ *
+ * The structure typedef is in dtk_list.h
+ */
 struct _DtkList {
        DtkListItem * first;
        DtkListItem * last;
@@ -45,6 +72,11 @@ struct _DtkList {
 
 // Function definitions
 
+/**
+ * Creates a new instance of the class.
+ *
+ * @return The newly created object.
+ */
 DtkList * dtk_list_new() {
        DtkList * data;
        
@@ -53,6 +85,13 @@ DtkList * dtk_list_new() {
        return data;
 }
 
+/**
+ * Deletes an instance of the class, freeing up the memory allocated to it.
+ *
+ * This will also delete all items contained in the list.
+ *
+ * @param data The instance to free.
+ */
 void dtk_list_delete(DtkList * data) {
        DtkListItem * item;
        DtkListItem * next;
@@ -70,6 +109,16 @@ void dtk_list_delete(DtkList * data) {
        }
 }
 
+/**
+ * Adds an item to the list.
+ *
+ * This adds a Dtk item to the list. It's primarily for internal use and when
+ * adding DTKs to the list it's usually more appropriate to use the
+ * \ref dtk_list_add_diagnosis() function.
+ *
+ * @param data The list to append to.
+ * @param dtk The DTK to append.
+ */
 void dtk_list_append(DtkList * data, Dtk * dtk) {
        DtkListItem * item;
        
@@ -86,21 +135,55 @@ void dtk_list_append(DtkList * data, Dtk * dtk) {
        }
 }
 
+/**
+ * Returns the first item in the list.
+ *
+ * Useful for iterating through the items in the list.
+ *
+ * @param data The list to operate on.
+ * @return The first item of the list.
+ */
 DtkListItem const * dtk_list_first(DtkList const * data) {
        return data->first;
 }
 
+/**
+ * Returns the next item in the list.
+ *
+ * Useful for iterating through the items in the list.
+ *
+ * @param data The current item in the list.
+ * @return The next item in the list following the current item.
+ */
 DtkListItem const * dtk_list_next(DtkListItem const * data) {
        return data->next;
 }
 
+/**
+ * Returns the Dtk item contained in this list item.
+ *
+ * @param data The current item in the list.
+ * @return The Dtk instance stored in the list element.
+ */
 Dtk const * dtk_list_get_dtk(DtkListItem const * data) {
        return data->dtk;
 }
 
+/**
+ * Adds Dtk data to the list.
+ *
+ * The dtk_bytes buffer passed in must contain exactly DTK_SIZE (16) bytes of
+ * data. It doen't have to be null terminated.
+ *
+ * @param data The current list to operate on.
+ * @param dtk_bytes The DTK value to add, in binary format.
+ * @param day_number The day number to associate with the DTK.
+ */
 void dtk_list_add_diagnosis(DtkList * data, unsigned char const * dtk_bytes, uint32_t day_number) {
        Dtk * dtk = dtk_new();
        dtk_assign(dtk, dtk_bytes, day_number);
        dtk_list_append(data, dtk);
 }
 
+/** @} addtogroup Containers*/
+