Add missing documentation

Author: saxbophone

sxbp/refine_figure_shrink_from_end.c

@@ -2,10 +2,11 @@
  * This source file forms part of sxbp, a library which generates experimental
  * 2D spiral-like shapes based on input binary data.
  *
- * This compilation unit provides the definition of `sxbp_refine_figure`, a
- * public function used to shorten the lines of an SXBP figure to something less
- * space-consuming, while still maintaining a pattern that has no collisions
- * between lines.
+ * This compilation unit provides the definition of
+ * `sxbp_refine_figure_shrink_from_end`, a public function providing a specific
+ * algorithm for refining a figure by attemptin to shrink all the lines from
+ * their safe 'default' lengths (as plotted by `sxbp_begin_figure`) to the
+ * shortest length possible, starting from the end and working backwards.
  *
  * Copyright (C) Joshua Saxby <[email protected]> 2016-2017, 2018
  *

sxbp/sxbp.h

@@ -625,7 +625,7 @@ sxbp_result_t sxbp_render_figure_to_bitmap(
  * callback.
  * @returns `SXBP_RESULT_OK` if the figure could be rendered successfully
  * @returns `SXBP_RESULT_FAIL_PRECONDITION` if `figure`, `buffer` or
- * `render_callback` is `NULL`
+ * `render_callback` are `NULL`
  * @returns Any other valid value for type `sxbp_result_t`, according to all
  * the possible error codes that can be returned by the given render callback.
  * @since v0.54.0
@@ -641,6 +641,9 @@ sxbp_result_t sxbp_render_figure(
 /**
  * @brief A dummy renderer function that does nothing
  * @details This exists for testing purposes only
+ * @warn This function is currently unusable because it always returns the
+ * "not implemented" failure error code
+ * @returns `SXBP_RESULT_FAIL_UNIMPLEMENTED`
  */
 sxbp_result_t sxbp_render_figure_to_null(
     const sxbp_figure_t* const figure,
@@ -651,6 +654,11 @@ sxbp_result_t sxbp_render_figure_to_null(
 
 /**
  * @brief Renders figures to PBM images
+ * @details If successful, the buffer will be filled with data which represents
+ * a binary format PBM image (P4 format).
+ * @returns `SXBP_RESULT_OK` if the figure could be rendered successfully
+ * @returns `SXBP_RESULT_FAIL_PRECONDITION` if `figure` or `buffer` are `NULL`
+ * @returns `SXBP_RESULT_FAIL_MEMORY` if a memory allocation error occurred
  */
 sxbp_result_t sxbp_render_figure_to_pbm(
     const sxbp_figure_t* const figure,