Even more C documentation

include/prism/util/pm_buffer.h

@@ -9,52 +9,125 @@
 #include <stdlib.h>
 #include <string.h>
 
-// A pm_buffer_t is a simple memory buffer that stores data in a contiguous
-// block of memory. It is used to store the serialized representation of a
-// prism tree.
+/**
+ * A pm_buffer_t is a simple memory buffer that stores data in a contiguous
+ * block of memory.
+ */
 typedef struct {
+    /** The length of the buffer in bytes. */
     size_t length;
+
+    /** The capacity of the buffer in bytes that has been allocated. */
     size_t capacity;
+
+    /** A pointer to the start of the buffer. */
     char *value;
 } pm_buffer_t;
 
-// Return the size of the pm_buffer_t struct.
+/**
+ * Return the size of the pm_buffer_t struct.
+ *
+ * @returns The size of the pm_buffer_t struct.
+ */
 PRISM_EXPORTED_FUNCTION size_t pm_buffer_sizeof(void);
 
-// Initialize a pm_buffer_t with the given capacity.
+/**
+ * Initialize a pm_buffer_t with the given capacity.
+ *
+ * @param buffer The buffer to initialize.
+ * @param capacity The capacity of the buffer.
+ * @returns True if the buffer was initialized successfully, false otherwise.
+ */
 bool pm_buffer_init_capacity(pm_buffer_t *buffer, size_t capacity);
 
-// Initialize a pm_buffer_t with its default values.
+/**
+ * Initialize a pm_buffer_t with its default values.
+ *
+ * @param buffer The buffer to initialize.
+ * @returns True if the buffer was initialized successfully, false otherwise.
+ */
 PRISM_EXPORTED_FUNCTION bool pm_buffer_init(pm_buffer_t *buffer);
 
-// Return the value of the buffer.
+/**
+ * Return the value of the buffer.
+ *
+ * @param buffer The buffer to get the value of.
+ * @returns The value of the buffer.
+ */
 PRISM_EXPORTED_FUNCTION char * pm_buffer_value(pm_buffer_t *buffer);
 
-// Return the length of the buffer.
+/**
+ * Return the length of the buffer.
+ *
+ * @param buffer The buffer to get the length of.
+ * @returns The length of the buffer.
+ */
 PRISM_EXPORTED_FUNCTION size_t pm_buffer_length(pm_buffer_t *buffer);
 
-// Append the given amount of space as zeroes to the buffer.
+/**
+ * Append the given amount of space as zeroes to the buffer.
+ *
+ * @param buffer The buffer to append to.
+ * @param length The amount of space to append and zero.
+ */
 void pm_buffer_append_zeroes(pm_buffer_t *buffer, size_t length);
 
-// Append a formatted string to the buffer.
+/**
+ * Append a formatted string to the buffer.
+ *
+ * @param buffer The buffer to append to.
+ * @param format The format string to append.
+ * @param ... The arguments to the format string.
+ */
 void pm_buffer_append_format(pm_buffer_t *buffer, const char *format, ...) PRISM_ATTRIBUTE_FORMAT(2, 3);
 
-// Append a string to the buffer.
+/**
+ * Append a string to the buffer.
+ *
+ * @param buffer The buffer to append to.
+ * @param value The string to append.
+ * @param length The length of the string to append.
+ */
 void pm_buffer_append_string(pm_buffer_t *buffer, const char *value, size_t length);
 
-// Append a list of bytes to the buffer.
+/**
+ * Append a list of bytes to the buffer.
+ *
+ * @param buffer The buffer to append to.
+ * @param value The bytes to append.
+ * @param length The length of the bytes to append.
+ */
 void pm_buffer_append_bytes(pm_buffer_t *buffer, const uint8_t *value, size_t length);
 
-// Append a single byte to the buffer.
+/**
+ * Append a single byte to the buffer.
+ *
+ * @param buffer The buffer to append to.
+ * @param value The byte to append.
+ */
 void pm_buffer_append_byte(pm_buffer_t *buffer, uint8_t value);
 
-// Append a 32-bit unsigned integer to the buffer.
+/**
+ * Append a 32-bit unsigned integer to the buffer as a variable-length integer.
+ *
+ * @param buffer The buffer to append to.
+ * @param value The integer to append.
+ */
 void pm_buffer_append_varint(pm_buffer_t *buffer, uint32_t value);
 
-// Append one buffer onto another.
+/**
+ * Concatenate one buffer onto another.
+ *
+ * @param destination The buffer to concatenate onto.
+ * @param source The buffer to concatenate.
+ */
 void pm_buffer_concat(pm_buffer_t *destination, const pm_buffer_t *source);
 
-// Free the memory associated with the buffer.
+/**
+ * Free the memory associated with the buffer.
+ *
+ * @param buffer The buffer to free.
+ */
 PRISM_EXPORTED_FUNCTION void pm_buffer_free(pm_buffer_t *buffer);
 
 #endif

include/prism/util/pm_char.h

@@ -7,85 +7,194 @@
 #include <stdbool.h>
 #include <stddef.h>
 
-// Returns the number of characters at the start of the string that are
-// whitespace. Disallows searching past the given maximum number of characters.
+/**
+ * Returns the number of characters at the start of the string that are
+ * whitespace. Disallows searching past the given maximum number of characters.
+ *
+ * @param string The string to search.
+ * @param length The maximum number of characters to search.
+ * @return The number of characters at the start of the string that are
+ *     whitespace.
+ */
 size_t pm_strspn_whitespace(const uint8_t *string, ptrdiff_t length);
 
-// Returns the number of characters at the start of the string that are
-// whitespace while also tracking the location of each newline. Disallows
-// searching past the given maximum number of characters.
+/**
+ * Returns the number of characters at the start of the string that are
+ * whitespace while also tracking the location of each newline. Disallows
+ * searching past the given maximum number of characters.
+ *
+ * @param string The string to search.
+ * @param length The maximum number of characters to search.
+ * @param newline_list The list of newlines to populate.
+ * @return The number of characters at the start of the string that are
+ *     whitespace.
+ */
 size_t
 pm_strspn_whitespace_newlines(const uint8_t *string, ptrdiff_t length, pm_newline_list_t *newline_list);
 
-// Returns the number of characters at the start of the string that are inline
-// whitespace. Disallows searching past the given maximum number of characters.
+/**
+ * Returns the number of characters at the start of the string that are inline
+ * whitespace. Disallows searching past the given maximum number of characters.
+ *
+ * @param string The string to search.
+ * @param length The maximum number of characters to search.
+ * @return The number of characters at the start of the string that are inline
+ *     whitespace.
+ */
 size_t pm_strspn_inline_whitespace(const uint8_t *string, ptrdiff_t length);
 
-// Returns the number of characters at the start of the string that are decimal
-// digits. Disallows searching past the given maximum number of characters.
+/**
+ * Returns the number of characters at the start of the string that are decimal
+ * digits. Disallows searching past the given maximum number of characters.
+ *
+ * @param string The string to search.
+ * @param length The maximum number of characters to search.
+ * @return The number of characters at the start of the string that are decimal
+ *     digits.
+ */
 size_t pm_strspn_decimal_digit(const uint8_t *string, ptrdiff_t length);
 
-// Returns the number of characters at the start of the string that are
-// hexadecimal digits. Disallows searching past the given maximum number of
-// characters.
+/**
+ * Returns the number of characters at the start of the string that are
+ * hexadecimal digits. Disallows searching past the given maximum number of
+ * characters.
+ *
+ * @param string The string to search.
+ * @param length The maximum number of characters to search.
+ * @return The number of characters at the start of the string that are
+ *     hexadecimal digits.
+ */
 size_t pm_strspn_hexadecimal_digit(const uint8_t *string, ptrdiff_t length);
 
-// Returns the number of characters at the start of the string that are octal
-// digits or underscores. Disallows searching past the given maximum number of
-// characters.
-//
-// If multiple underscores are found in a row or if an underscore is
-// found at the end of the number, then the invalid pointer is set to the index
-// of the first invalid underscore.
+/**
+ * Returns the number of characters at the start of the string that are octal
+ * digits or underscores. Disallows searching past the given maximum number of
+ * characters.
+ *
+ * If multiple underscores are found in a row or if an underscore is
+ * found at the end of the number, then the invalid pointer is set to the index
+ * of the first invalid underscore.
+ *
+ * @param string The string to search.
+ * @param length The maximum number of characters to search.
+ * @param invalid The pointer to set to the index of the first invalid
+ *     underscore.
+ * @return The number of characters at the start of the string that are octal
+ *     digits or underscores.
+ */
 size_t pm_strspn_octal_number(const uint8_t *string, ptrdiff_t length, const uint8_t **invalid);
 
-// Returns the number of characters at the start of the string that are decimal
-// digits or underscores. Disallows searching past the given maximum number of
-// characters.
-//
-// If multiple underscores are found in a row or if an underscore is
-// found at the end of the number, then the invalid pointer is set to the index
-// of the first invalid underscore.
+/**
+ * Returns the number of characters at the start of the string that are decimal
+ * digits or underscores. Disallows searching past the given maximum number of
+ * characters.
+ *
+ * If multiple underscores are found in a row or if an underscore is
+ * found at the end of the number, then the invalid pointer is set to the index
+ * of the first invalid underscore.
+ *
+ * @param string The string to search.
+ * @param length The maximum number of characters to search.
+ * @param invalid The pointer to set to the index of the first invalid
+ *     underscore.
+ * @return The number of characters at the start of the string that are decimal
+ *     digits or underscores.
+ */
 size_t pm_strspn_decimal_number(const uint8_t *string, ptrdiff_t length, const uint8_t **invalid);
 
-// Returns the number of characters at the start of the string that are
-// hexadecimal digits or underscores. Disallows searching past the given maximum
-// number of characters.
-//
-// If multiple underscores are found in a row or if an underscore is
-// found at the end of the number, then the invalid pointer is set to the index
-// of the first invalid underscore.
+/**
+ * Returns the number of characters at the start of the string that are
+ * hexadecimal digits or underscores. Disallows searching past the given maximum
+ * number of characters.
+ *
+ * If multiple underscores are found in a row or if an underscore is
+ * found at the end of the number, then the invalid pointer is set to the index
+ * of the first invalid underscore.
+ *
+ * @param string The string to search.
+ * @param length The maximum number of characters to search.
+ * @param invalid The pointer to set to the index of the first invalid
+ *     underscore.
+ * @return The number of characters at the start of the string that are
+ *     hexadecimal digits or underscores.
+ */
 size_t pm_strspn_hexadecimal_number(const uint8_t *string, ptrdiff_t length, const uint8_t **invalid);
 
-// Returns the number of characters at the start of the string that are regexp
-// options. Disallows searching past the given maximum number of characters.
+/**
+ * Returns the number of characters at the start of the string that are regexp
+ * options. Disallows searching past the given maximum number of characters.
+ *
+ * @param string The string to search.
+ * @param length The maximum number of characters to search.
+ * @return The number of characters at the start of the string that are regexp
+ *     options.
+ */
 size_t pm_strspn_regexp_option(const uint8_t *string, ptrdiff_t length);
 
-// Returns the number of characters at the start of the string that are binary
-// digits or underscores. Disallows searching past the given maximum number of
-// characters.
-//
-// If multiple underscores are found in a row or if an underscore is
-// found at the end of the number, then the invalid pointer is set to the index
-// of the first invalid underscore.
+/**
+ * Returns the number of characters at the start of the string that are binary
+ * digits or underscores. Disallows searching past the given maximum number of
+ * characters.
+ *
+ * If multiple underscores are found in a row or if an underscore is
+ * found at the end of the number, then the invalid pointer is set to the index
+ * of the first invalid underscore.
+ *
+ * @param string The string to search.
+ * @param length The maximum number of characters to search.
+ * @param invalid The pointer to set to the index of the first invalid
+ *     underscore.
+ * @return The number of characters at the start of the string that are binary
+ *     digits or underscores.
+ */
 size_t pm_strspn_binary_number(const uint8_t *string, ptrdiff_t length, const uint8_t **invalid);
 
-// Returns true if the given character is a whitespace character.
+/**
+ * Returns true if the given character is a whitespace character.
+ *
+ * @param b The character to check.
+ * @return True if the given character is a whitespace character.
+ */
 bool pm_char_is_whitespace(const uint8_t b);
 
-// Returns true if the given character is an inline whitespace character.
+/**
+ * Returns true if the given character is an inline whitespace character.
+ *
+ * @param b The character to check.
+ * @return True if the given character is an inline whitespace character.
+ */
 bool pm_char_is_inline_whitespace(const uint8_t b);
 
-// Returns true if the given character is a binary digit.
+/**
+ * Returns true if the given character is a binary digit.
+ *
+ * @param b The character to check.
+ * @return True if the given character is a binary digit.
+ */
 bool pm_char_is_binary_digit(const uint8_t b);
 
-// Returns true if the given character is an octal digit.
+/**
+ * Returns true if the given character is an octal digit.
+ *
+ * @param b The character to check.
+ * @return True if the given character is an octal digit.
+ */
 bool pm_char_is_octal_digit(const uint8_t b);
 
-// Returns true if the given character is a decimal digit.
+/**
+ * Returns true if the given character is a decimal digit.
+ *
+ * @param b The character to check.
+ * @return True if the given character is a decimal digit.
+ */
 bool pm_char_is_decimal_digit(const uint8_t b);
 
-// Returns true if the given character is a hexadecimal digit.
+/**
+ * Returns true if the given character is a hexadecimal digit.
+ *
+ * @param b The character to check.
+ * @return True if the given character is a hexadecimal digit.
+ */
 bool pm_char_is_hexadecimal_digit(const uint8_t b);
 
 #endif