docs, kinda

bindings/c/include/ipl3checksum/checksum.h

@@ -13,6 +13,22 @@ extern "C"
 {
 #endif
 
+/**
+ * Calculates the checksum required by an official CIC of a N64 ROM.
+ *
+ * ## Arguments
+ *
+ * * `dst_checksum0` - Pointer where the first word of the calculated checksum will be placed.
+ * * `dst_checksum1` - Pointer where the second word of the calculated checksum will be placed.
+ * * `rom_bytes_len` - Bytes length of the input `rom_bytes`.
+ * * `rom_bytes` - The bytes of the N64 ROM in big endian format. It must have a minimum size of 0x101000 bytes.
+ * * `kind` - The CIC kind variation used to calculate the checksum.
+ *
+ * ## Return
+ *
+ * * `Ipl3Checksum_Error` indicating either a successful execution or the cause for failing.
+ *   If execution fails then `dst_checksum0` and `dst_checksum1` are left untouched.
+ */
 Ipl3Checksum_Error ipl3checksum_calculate_checksum(
     uint32_t *dst_checksum0,
     uint32_t *dst_checksum1,
@@ -21,6 +37,24 @@ Ipl3Checksum_Error ipl3checksum_calculate_checksum(
     Ipl3Checksum_CICKind kind
 );
 
+/**
+ * Calculates the checksum required by an official CIC of a N64 ROM.
+ *
+ * This function will try to autodetect the CIC kind automatically.
+ * If it fails to detect it then an error will be returned.
+ *
+ * ## Arguments
+ *
+ * * `dst_checksum0` - Pointer where the first word of the calculated checksum will be placed.
+ * * `dst_checksum1` - Pointer where the second word of the calculated checksum will be placed.
+ * * `rom_bytes_len` - Bytes length of the input `rom_bytes`.
+ * * `rom_bytes` - The bytes of the N64 ROM in big endian format. It must have a minimum size of 0x101000 bytes.
+ *
+ * ## Return
+ *
+ * * `Ipl3Checksum_Error` indicating either a successful execution or the cause for failing.
+ *   If execution fails then `dst_checksum0` and `dst_checksum1` are left untouched.
+ */
 Ipl3Checksum_Error ipl3checksum_calculate_checksum_autodetect(
     uint32_t *dst_checksum0,
     uint32_t *dst_checksum1,

bindings/c/include/ipl3checksum/cickinds.h

@@ -27,10 +27,26 @@ uint32_t ipl3checksum_cickind_get_seed(Ipl3Checksum_CICKind self);
 
 uint32_t ipl3checksum_cickind_get_magic(Ipl3Checksum_CICKind self);
 
+/**
+ * Returns the md5 hash for the specified CIC kind.
+ *
+ * If no errors happen (return is an `Ipl3Checksum_Error_Okay`), then the hash
+ * is stored  on `dst_hash`.
+ * This string is dynamically allocated by the library and it should be freed
+ * (by passing it to `ipl3checksum_free_string`) to avoid memory leaks.
+ */
 Ipl3Checksum_Error ipl3checksum_cickind_get_hash_md5(Ipl3Checksum_CICKind self, char **dst_hash);
 
 Ipl3Checksum_Error ipl3checksum_cickind_from_hash_md5(Ipl3Checksum_CICKind *kind_dst, const char *hash_str);
 
+/**
+ * Returns an human readable name for the specified CIC kind.
+ *
+ * If no errors happen (return is an `Ipl3Checksum_Error_Okay`), then the name
+ * is stored  on `dst_name`.
+ * This string is dynamically allocated by the library and it should be freed
+ * (by passing it to `ipl3checksum_free_string`) to avoid memory leaks.
+ */
 Ipl3Checksum_Error ipl3checksum_cickind_get_name(Ipl3Checksum_CICKind self, char **dst_name);
 
 Ipl3Checksum_Error ipl3checksum_cickind_from_name(Ipl3Checksum_CICKind *kind_dst, const char *name);

bindings/c/include/ipl3checksum/detect.h

@@ -13,12 +13,45 @@ extern "C"
 {
 #endif
 
+/**
+ * Tries to detect an IPL3 binary.
+ *
+ * The argument to this function must be exactly the IPL3 binary, meaning the
+ * binary size must match exactly the one of an IPL3 binary.
+ *
+ * ## Arguments
+ *
+ * * `dst_kind` - Pointer where the detected kind will be set to.
+ * * `raw_bytes_len` - Bytes length of the input `raw_bytes`.
+ * * `raw_bytes` - Bytes of an IPL3 binary in big endian format.
+ *
+ * ## Return
+ *
+ * * `Ipl3Checksum_Error` indicating either a successful execution or the cause
+ *   for failing. If execution fails then `dst_kind` is left untouched.
+ */
 Ipl3Checksum_Error ipl3checksum_detect_cic_raw(
     Ipl3Checksum_CICKind *dst_kind,
     size_t raw_bytes_len,
     const uint8_t *raw_bytes
 );
 
+/**
+ * Tries to detect an IPL3 in a ROM.
+ *
+ * The argument to this function must be a ROM in big endian format.
+ *
+ * ## Arguments
+ *
+ * * `dst_kind` - Pointer where the detected kind will be set to.
+ * * `raw_bytes_len` - Bytes length of the input `rom_bytes`.
+ * * `rom_bytes` - ROM binary in big endian format.
+ *
+ * ## Return
+ *
+ * * `Ipl3Checksum_Error` indicating either a successful execution or the cause
+ *   for failing. If execution fails then `dst_kind` is left untouched.
+ */
 Ipl3Checksum_Error ipl3checksum_detect_cic(
     Ipl3Checksum_CICKind *dst_kind,
     size_t rom_bytes_len,

bindings/c/include/ipl3checksum/error.h

@@ -22,6 +22,21 @@ typedef enum Ipl3Checksum_Error_Tag {
     Ipl3Checksum_Error_StringConversion,
 } Ipl3Checksum_Error_Tag;
 
+/**
+ * Most functions of this library return a Ipl3Checksum_Error object which
+ * indicates if the function ended successfully or if it failed (and why it
+ * failed). If a function is expected to return a value on success, then said
+ * value will be set via argument pointers.
+ *
+ * A successful execution has the `.tag` member set to `Ipl3Checksum_Error_Okay`,
+ * everything else is considered an error.
+ *
+ * If an error ocurred then the argument dst pointers will be left untouched.
+ *
+ * The `.payload` union member may have extra information on why the function
+ * call failed. This information is set only for a few selected
+ * `Ipl3Checksum_Error_Tag` tags.
+ */
 typedef struct Ipl3Checksum_Error {
     Ipl3Checksum_Error_Tag tag;
     union Ipl3Checksum_Error_Payload {

bindings/c/include/ipl3checksum/utils.h

@@ -4,6 +4,9 @@
 
 #include "error.h"
 
+/**
+ * Free a string returned by the ipl3checksum library.
+ */
 Ipl3Checksum_Error ipl3checksum_free_string(char *s);
 
 #endif

src/rs/checksum.rs

@@ -206,7 +206,8 @@ pub fn calculate_checksum(
 
 /// Calculates the checksum required by an official CIC of a N64 ROM.
 ///
-/// This function will try to autodetect the CIC kind automatically. If it fails to detect it then it will return `None`.
+/// This function will try to autodetect the CIC kind automatically.
+/// If it fails to detect it then an error will be returned.
 ///
 /// ## Arguments
 ///