Add remaining documentation

[libcontrac.git] / src / rpi_list.c

diff --git a/src/rpi_list.c b/src/rpi_list.c
index a21b0da..a74e0a9 100644 (file)
--- a/src/rpi_list.c
+++ b/src/rpi_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 RPIs 
  * @section DESCRIPTION
  *
+ * This class allows the simplified management of lists of Rpi objects. This is
+ * useful when checking DTKs received from a Diagnosis Server with RPIs
+ * captured over Bluetooth. Combined with the \ref DtkList class the two can
+ * be easily stored and passed into the \ref match_list_find_matches() function.
  *
- *
+ */
+
+/** \addtogroup Containers
+ *  @{
  */
 
 // Includes
@@ -32,11 +40,30 @@
 
 // Structures
 
+/**
+ * @brief An RPI list element
+ *
+ * This is an opaque structure that represents a single item in the list and
+ * contains an Rpi instance.
+ * 
+ * The structure typedef is in rpi_list.h
+ */
 struct _RpiListItem {
        Rpi * rpi;
        RpiListItem * next;
 };
 
+/**
+ * @brief The head of an RPI list
+ *
+ * This is an opaque structure that represents the head of a list of Rpi
+ * 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 _RpiList {
        RpiListItem * first;
        RpiListItem * last;
@@ -46,6 +73,11 @@ struct _RpiList {
 
 // Function definitions
 
+/**
+ * Creates a new instance of the class.
+ *
+ * @return The newly created object.
+ */
 RpiList * rpi_list_new() {
        RpiList * data;
        
@@ -54,6 +86,13 @@ RpiList * rpi_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 rpi_list_delete(RpiList * data) {
        RpiListItem * item;
        RpiListItem * next;
@@ -71,6 +110,16 @@ void rpi_list_delete(RpiList * data) {
        }
 }
 
+/**
+ * Adds an item to the list.
+ *
+ * This adds an Rpi item to the list. It's primarily for internal use and when
+ * adding RPIs to the list it's usually more appropriate to use the
+ * \ref rpi_list_add_beacon() function.
+ *
+ * @param data The list to append to.
+ * @param rpi The RPI to append.
+ */
 void rpi_list_append(RpiList * data, Rpi * rpi) {
        RpiListItem * item;
        
@@ -87,24 +136,56 @@ void rpi_list_append(RpiList * data, Rpi * rpi) {
        }
 }
 
+/**
+ * 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.
+ */
 RpiListItem const * rpi_list_first(RpiList 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.
+ */
 RpiListItem const * rpi_list_next(RpiListItem const * data) {
        return data->next;
 }
 
+/**
+ * Returns the Rpi item contained in this list item.
+ *
+ * @param data The current item in the list.
+ * @return The Rpi instance stored in the list element.
+ */
 Rpi const * rpi_list_get_rpi(RpiListItem const * data) {
        return data->rpi;
 }
 
+/**
+ * Adds Rpi data to the list.
+ *
+ * The rpi_bytes buffer passed in must contain exactly RPI_SIZE (16) bytes of
+ * data. It doen't have to be null terminated.
+ *
+ * @param data The current list to operate on.
+ * @param rpi_bytes The RPI value to add, in binary format.
+ * @param time_interval_number The time interval number to associate with the
+ *        RPI.
+ */
 void rpi_list_add_beacon(RpiList * data, unsigned char const * rpi_bytes, uint8_t time_interval_number) {
        Rpi * rpi = rpi_new();
        rpi_assign(rpi, rpi_bytes, time_interval_number);
        rpi_list_append(data, rpi);
 }
 
-
-
+/** @} addtogroup Containers*/