prism 0.16.0 → 0.17.0

data/include/prism/pack.h

@@ -1,3 +1,8 @@
+/**
+ * @file pack.h
+ *
+ * A pack template string parser.
+ */
 #ifndef PRISM_PACK_H
 #define PRISM_PACK_H
 
@@ -6,15 +11,18 @@
 #include <stdint.h>
 #include <stdlib.h>
 
+/** The version of the pack template language that we are parsing. */
 typedef enum pm_pack_version {
     PM_PACK_VERSION_3_2_0
 } pm_pack_version;
 
+/** The type of pack template we are parsing. */
 typedef enum pm_pack_variant {
     PM_PACK_VARIANT_PACK,
     PM_PACK_VARIANT_UNPACK
 } pm_pack_variant;
 
+/** A directive within the pack template. */
 typedef enum pm_pack_type {
     PM_PACK_SPACE,
     PM_PACK_COMMENT,
@@ -40,12 +48,14 @@ typedef enum pm_pack_type {
     PM_PACK_END
 } pm_pack_type;
 
+/** The signness of a pack directive. */
 typedef enum pm_pack_signed {
     PM_PACK_UNSIGNED,
     PM_PACK_SIGNED,
     PM_PACK_SIGNED_NA
 } pm_pack_signed;
 
+/** The endianness of a pack directive. */
 typedef enum pm_pack_endian {
     PM_PACK_AGNOSTIC_ENDIAN,
     PM_PACK_LITTLE_ENDIAN,      // aka 'VAX', or 'V'
@@ -54,6 +64,7 @@ typedef enum pm_pack_endian {
     PM_PACK_ENDIAN_NA
 } pm_pack_endian;
 
+/** The size of an integer pack directive. */
 typedef enum pm_pack_size {
     PM_PACK_SIZE_SHORT,
     PM_PACK_SIZE_INT,
@@ -67,6 +78,7 @@ typedef enum pm_pack_size {
     PM_PACK_SIZE_NA
 } pm_pack_size;
 
+/** The type of length of a pack directive. */
 typedef enum pm_pack_length_type {
     PM_PACK_LENGTH_FIXED,
     PM_PACK_LENGTH_MAX,
@@ -74,6 +86,7 @@ typedef enum pm_pack_length_type {
     PM_PACK_LENGTH_NA
 } pm_pack_length_type;
 
+/** The type of encoding for a pack template string. */
 typedef enum pm_pack_encoding {
     PM_PACK_ENCODING_START,
     PM_PACK_ENCODING_ASCII_8BIT,
@@ -81,6 +94,7 @@ typedef enum pm_pack_encoding {
     PM_PACK_ENCODING_UTF_8
 } pm_pack_encoding;
 
+/** The result of parsing a pack template. */
 typedef enum pm_pack_result {
     PM_PACK_OK,
     PM_PACK_ERROR_UNSUPPORTED_DIRECTIVE,
@@ -90,39 +104,31 @@ typedef enum pm_pack_result {
     PM_PACK_ERROR_DOUBLE_ENDIAN
 } pm_pack_result;
 
-// Parse a single directive from a pack or unpack format string.
-//
-// Parameters:
-//  - [in] pm_pack_version version    the version of Ruby
-//  - [in] pm_pack_variant variant    pack or unpack
-//  - [in out] const char **format    the start of the next directive to parse
-//      on calling, and advanced beyond the parsed directive on return, or as
-//      much of it as was consumed until an error was encountered
-//  - [in] const char *format_end     the end of the format string
-//  - [out] pm_pack_type *type        the type of the directive
-//  - [out] pm_pack_signed *signed_type
-//                                    whether the value is signed
-//  - [out] pm_pack_endian *endian    the endianness of the value
-//  - [out] pm_pack_size *size        the size of the value
-//  - [out] pm_pack_length_type *length_type
-//                                    what kind of length is specified
-//  - [out] size_t *length            the length of the directive
-//  - [in out] pm_pack_encoding *encoding
-//                                    takes the current encoding of the string
-//      which would result from parsing the whole format string, and returns a
-//      possibly changed directive - the encoding should be
-//      PM_PACK_ENCODING_START when pm_pack_parse is called for the first
-//      directive in a format string
-//
-// Return:
-//  - PM_PACK_OK on success
-//  - PM_PACK_ERROR_* on error
-//
-// Notes:
-//   Consult Ruby documentation for the meaning of directives.
+/**
+ * Parse a single directive from a pack or unpack format string.
+ *
+ * @param variant (in) pack or unpack
+ * @param format (in, out) the start of the next directive to parse on calling,
+ *     and advanced beyond the parsed directive on return, or as much of it as
+ *     was consumed until an error was encountered
+ * @param format_end (in) the end of the format string
+ * @param type (out) the type of the directive
+ * @param signed_type (out) whether the value is signed
+ * @param endian (out) the endianness of the value
+ * @param size (out) the size of the value
+ * @param length_type (out) what kind of length is specified
+ * @param length (out) the length of the directive
+ * @param encoding (in, out) takes the current encoding of the string which
+ *     would result from parsing the whole format string, and returns a possibly
+ *     changed directive - the encoding should be `PM_PACK_ENCODING_START` when
+ *     pm_pack_parse is called for the first directive in a format string
+ *
+ * @return `PM_PACK_OK` on success or `PM_PACK_ERROR_*` on error
+ * @note Consult Ruby documentation for the meaning of directives.
+ */
 PRISM_EXPORTED_FUNCTION pm_pack_result
 pm_pack_parse(
-    pm_pack_variant variant_arg,
+    pm_pack_variant variant,
     const char **format,
     const char *format_end,
     pm_pack_type *type,
@@ -134,8 +140,13 @@ pm_pack_parse(
     pm_pack_encoding *encoding
 );
 
-// prism abstracts sizes away from the native system - this converts an abstract
-// size to a native size.
+/**
+ * Prism abstracts sizes away from the native system - this converts an abstract
+ * size to a native size.
+ *
+ * @param size The abstract size to convert.
+ * @return The native size.
+ */
 PRISM_EXPORTED_FUNCTION size_t pm_size_to_native(pm_pack_size size);
 
 #endif