Merge pull request #155 from saxbophone/josh/doxygen

Add Doxygen

Author: saxbophone

.gitignore

@@ -42,3 +42,6 @@ Makefile
 cmake_install.cmake
 CTestTestfile.cmake
 install_manifest.txt
+
+# Doxygen build folder
+doc/

Doxyfile

@@ -2,10 +2,6 @@
  * This source file forms part of libsxbp, a library which generates
  * experimental 2D spiral-like shapes based on input binary data.
  *
- * This compilation unit provides basic functions to initialise a spiral.
- *
- *
- *
  * Copyright (C) 2016, Joshua Saxby [email protected]
  *
  * This program is free software: you can redistribute it and/or modify
@@ -32,33 +28,16 @@
 extern "C"{
 #endif
 
-/*
- * when facing the direction specified by current, return the direction that
- * will be faced when turning in the rotational direction specified by turn.
- */
 sxbp_direction_t sxbp_change_direction(
     sxbp_direction_t current, sxbp_rotation_t turn
 ) {
     return (current + turn) % 4U;
 }
 
-/*
- * returns a spiral struct with all fields initialised to 0
- */
 sxbp_spiral_t sxbp_blank_spiral() {
     return (sxbp_spiral_t){0, NULL, {{NULL, 0}, 0}, false, 0, 0, 0};
 }
 
-/*
- * given a buffer_t full of data, and a pointer to a blank spiral_t
- * struct, populates the spiral struct from the data in the buffer
- * this converts the 0s and 1s in the data into UP, LEFT, DOWN, RIGHT
- * instructions which are then used to build the pattern.
- * returns a status_t struct with error information (if needed)
- *
- * Asserts:
- * - That the spiral struct pointed to has its pointer attributes set to NULL
- */
 sxbp_status_t sxbp_init_spiral(sxbp_buffer_t buffer, sxbp_spiral_t* spiral) {
     // preconditional assertions
     assert(spiral->lines == NULL);

sxbp/initialise.c

@@ -1,24 +1,29 @@
 /*
  * This source file forms part of libsxbp, a library which generates
  * experimental 2D spiral-like shapes based on input binary data.
+ */
+
+/**
+ * @file
  *
- * This compilation unit provides basic functions to initialise a spiral.
- *
+ * @brief This compilation unit provides basic functions to initialise a spiral.
  *
+ * @author Joshua Saxby <[email protected]
+ * @date 2016
  *
- * Copyright (C) 2016, Joshua Saxby [email protected]
+ * @copyright Copyright (C) Joshua Saxby 2016
  *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Affero General Public License (version 3),
- * as published by the Free Software Foundation.
+ * @copyright This program is free software: you can redistribute it and/or
+ * modify it under the terms of the GNU Affero General Public License
+ * (version 3), as published by the Free Software Foundation.
  *
- * This program is distributed in the hope that it will be useful,
+ * @copyright 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 Affero General Public License for more details.
  *
- * You should have received a copy of the GNU Affero General Public License
- * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ * @copyright You should have received a copy of the GNU Affero General Public
+ * License along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 #ifndef SAXBOPHONE_SAXBOSPIRAL_INITIALISE_H
 #define SAXBOPHONE_SAXBOSPIRAL_INITIALISE_H
@@ -30,28 +35,47 @@
 extern "C"{
 #endif
 
-/*
- * when facing the direction specified by current, return the direction that
- * will be faced when turning in the rotational direction specified by turn.
+/**
+ * @brief Gets the direction which is clockwise or anti-clockwise to the current
+ * direction.
+ * @details Given a current direction and a rotational direction, return the new
+ * direction which would be faced after turning 90 degrees in the given
+ * rotational direction.
+ *
+ * @param current The current direction to turn from.
+ * @param turn The rotational direction to turn in.
+ * @return The new direction which will be faced after turning.
  */
 sxbp_direction_t sxbp_change_direction(
     sxbp_direction_t current, sxbp_rotation_t turn
 );
 
-/*
- * returns a spiral struct with all fields initialised to 0
+/**
+ * @brief Builds a blank spiral struct.
+ * @details This is a convenience function, as the struct has many fields. This
+ * function will create a spiral struct with all of these fields initialised to
+ * 0 or their default 'blank' state. No memory is allocated.
+ *
+ * @return A blank spiral struct with all fields initialised to 0 or blank values.
  */
 sxbp_spiral_t sxbp_blank_spiral();
 
-/*
- * given a buffer_t full of data, and a pointer to a blank spiral_t
- * struct, populates the spiral struct from the data in the buffer
- * this converts the 0s and 1s in the data into UP, LEFT, DOWN, RIGHT
- * instructions which are then used to build the pattern.
- * returns a status_t struct with error information (if needed)
- *
- * Asserts:
- * - That the spiral struct pointed to has its pointer attributes set to NULL
+/**
+ * @brief Builds a partially-complete spiral from binary input data stored in a
+ * buffer.
+ * @details This converts the 0s and 1s in the buffer data into UP, LEFT, DOWN,
+ * RIGHT instructions which are then used to build the pattern. Only the line
+ * directions are calculated at this point, all line lengths are 0.
+ *
+ * @param buffer A buffer containing at least one byte of data, used to
+ * determine the directions of the lines in the spiral it will create.
+ * @param spiral [out] Spiral object which the line directions will be written
+ * to.
+ * @return SXBP_OPERATION_OK on success.
+ * @return SXBP_MALLOC_REFUSED on memory allocation failure.
+ *
+ * @note Asserts:
+ * - That all the pointer members of parameter spiral are set to NULL
  */
 sxbp_status_t sxbp_init_spiral(sxbp_buffer_t buffer, sxbp_spiral_t* spiral);
 

sxbp/initialise.h

@@ -2,11 +2,6 @@
  * This source file forms part of libsxbp, a library which generates
  * experimental 2D spiral-like shapes based on input binary data.
  *
- * This compilation unit provides functions for plotting and caching the points
- * which make up the lines of a spiral.
- *
- *
- *
  * Copyright (C) 2016, Joshua Saxby [email protected]
  *
  * This program is free software: you can redistribute it and/or modify
@@ -32,13 +27,6 @@
 extern "C"{
 #endif
 
-/*
- * returns the sum of all line lengths within the given indexes
- *
- * Asserts:
- * - That start and end indexes are less than or equal to the spiral size
- * - That spiral.lines is not NULL
- */
 size_t sxbp_sum_lines(sxbp_spiral_t spiral, size_t start, size_t end) {
     // preconditional assertions
     assert(start <= spiral.size);
@@ -51,21 +39,6 @@ size_t sxbp_sum_lines(sxbp_spiral_t spiral, size_t start, size_t end) {
     return size;
 }
 
-/*
- * given a spiral_t struct, a pointer to a co_ord_array_t, a pair of co-ords
- * specifying the start point and indexes of the lowest and highest line
- * segments to use, write to the co_ord_array_t struct all the co-ordinates of
- * the line segments of the struct according to the current directions and
- * lengths of the lines in the spiral.
- * each line segment is only one unit long, meaning multiple ones are needed for
- * lines longer than one unit.
- * returns a status struct with error information (if any)
- *
- * Asserts:
- * - That the output struct's items pointer is NULL
- * - That start and end indexes are less than or equal to the spiral size
- * - That spiral.lines is not NULL
- */
 sxbp_status_t sxbp_spiral_points(
     sxbp_spiral_t spiral, sxbp_co_ord_array_t* output,
     sxbp_co_ord_t start_point, size_t start, size_t end
@@ -110,19 +83,6 @@ sxbp_status_t sxbp_spiral_points(
     return result;
 }
 
-/*
- * given a pointer to a spiral struct and limit, which is the index of the last
- * line to use, calculate and store the co-ordinates of all line segments that
- * would make up the spiral if the current lengths and directions were used.
- * each line segment is only one unit long, meaning multiple ones are needed for
- * lines longer than one unit. The co-ords are stored in the spiral's
- * co_ord_cache member and are re-used if they are still valid
- * returns a status struct with error information (if any)
- *
- * Asserts:
- * - That spiral->lines is not NULL
- * - That limit is less than or equal to spiral->size
- */
 sxbp_status_t sxbp_cache_spiral_points(sxbp_spiral_t* spiral, size_t limit) {
     // preconditional assertions
     assert(spiral->lines != NULL);

sxbp/plot.c

@@ -1,25 +1,30 @@
 /*
  * This source file forms part of libsxbp, a library which generates
  * experimental 2D spiral-like shapes based on input binary data.
+ */
+
+/**
+ * @file
  *
- * This compilation unit provides functions for plotting and caching the points
- * which make up the lines of a spiral.
- *
+ * @brief This compilation unit provides functions for plotting and caching the
+ * points which make up the lines of a spiral.
  *
+ * @author Joshua Saxby <[email protected]
+ * @date 2016
  *
- * Copyright (C) 2016, Joshua Saxby [email protected]
+ * @copyright Copyright (C) Joshua Saxby 2016
  *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Affero General Public License (version 3),
- * as published by the Free Software Foundation.
+ * @copyright This program is free software: you can redistribute it and/or
+ * modify it under the terms of the GNU Affero General Public License
+ * (version 3), as published by the Free Software Foundation.
  *
- * This program is distributed in the hope that it will be useful,
+ * @copyright 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 Affero General Public License for more details.
  *
- * You should have received a copy of the GNU Affero General Public License
- * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ * @copyright You should have received a copy of the GNU Affero General Public
+ * License along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 #ifndef SAXBOPHONE_SAXBOSPIRAL_PLOT_H
 #define SAXBOPHONE_SAXBOSPIRAL_PLOT_H
@@ -33,45 +38,78 @@
 extern "C"{
 #endif
 
-/*
- * returns the sum of all line lengths within the given indexes
+/**
+ * @brief Calculates the sum of all line lengths in this spiral within the given
+ * start and end indexes.
+ * @details params start and end specify the range of line indexes to use for the
+ * lines which are to be summed. These are inclusive of the lower bound but
+ * exclusive of the upper bound.
+ *
+ * @param spiral The spiral of which line lengths should be summed.
+ * @param start The index of the first line to include in those of which lengths
+ * should be summed.
+ * @param end The index of the line after the last line to include in those of
+ * which lengths should be summed.
+ * @return The sum of the lengths of all the lines in the given range.
  *
- * Asserts:
+ * @note Asserts:
  * - That start and end indexes are less than or equal to the spiral size
  * - That spiral.lines is not NULL
+ *
+ * @todo Might also need to add an assertion to check that end is never less
+ * than start.
  */
 size_t sxbp_sum_lines(sxbp_spiral_t spiral, size_t start, size_t end);
 
-/*
- * given a spiral_t struct, a pointer to a co_ord_array_t, a pair of co-ords
- * specifying the start point and indexes of the lowest and highest line
- * segments to use, write to the co_ord_array_t struct all the co-ordinates of
- * the line segments of the struct according to the current directions and
- * lengths of the lines in the spiral.
- * each line segment is only one unit long, meaning multiple ones are needed for
- * lines longer than one unit.
- * returns a status struct with error information (if any)
+/**
+ * @brief Calculates a series of co-ords for which trace a given part of a
+ * spiral line.
+ * @details The whole spiral may be calculated, or just a given segment of it.
+ * This is controlled by specifying which line to start at and which to end at.
+ * 
+ * @param spiral The spiral for which line co-ords should be calculated.
+ * @param output [out] The co-ords array which calculated co-ords should be
+ * written to.
+ * @param start_point The x/y co-ordinates at which the line being plotted
+ * originates at.
+ * @param start The index of the first line which makes up the segment which is
+ * being calculated.
+ * @param end The index of the line after the last line which makes up the
+ * segment which is being calculated.
+ * @return SXBP_OPERATION_OK on success.
+ * @return SXBP_MALLOC_REFUSED on memory allocation failure.
+ *
+ * @note For this function to do anything useful, the spiral should at least
+ * have some line lengths calculated, but this is not essential.
  *
- * Asserts:
- * - That the output struct's items pointer is NULL
+ * @note Asserts:
+ * - That output->items is NULL
  * - That start and end indexes are less than or equal to the spiral size
  * - That spiral.lines is not NULL
+ *
+ * @todo Might also need to add an assertion to check that end is never less
+ * than start.
  */
 sxbp_status_t sxbp_spiral_points(
     sxbp_spiral_t spiral, sxbp_co_ord_array_t* output,
     sxbp_co_ord_t start_point, size_t start, size_t end
 );
 
-/*
- * given a pointer to a spiral struct and limit, which is the index of the last
- * line to use, calculate and store the co-ordinates of all line segments that
- * would make up the spiral if the current lengths and directions were used.
- * each line segment is only one unit long, meaning multiple ones are needed for
- * lines longer than one unit. The co-ords are stored in the spiral's
- * co_ord_cache member and are re-used if they are still valid
- * returns a status struct with error information (if any)
+/**
+ * @brief Caches any uncached co-ords of the line of a spiral up to a given line
+ * index.
+ * @details If there are any outstanding co-ordinates which haven't been stored
+ * in the spiral's internal cache, then these will be calculated and stored in
+ * the cache. Subsequent identical calls will not incur the overhead of
+ * re-calculating these co-ords, provided the lengths of any of the spiral's
+ * lines are not changed in the process.
+ *
+ * @param spiral The spiral for which co-ords should be cached.
+ * @param limit The highest index of line for which co-ords should be cached to.
+ * @return SXBP_OPERATION_OK on success.
+ * @return SXBP_MALLOC_REFUSED on memory allocation failure.
  *
- * Asserts:
+ * @note Asserts:
  * - That spiral->lines is not NULL
  * - That limit is less than or equal to spiral->size
  */