docs: Added comments for 3 private functions (fixes #371)

include/private/inthelper.h

@@ -30,6 +30,26 @@
  */
 #  define MAX_INT_SIZE 50
 
+/**
+ * Converts a `size_t` value to an `int`, capping at `INT_MAX` if necessary.
+ *
+ * This helper prevents integer overflow when a `size_t` value must be used
+ * in an interface that accepts only signed integers. If `val` exceeds
+ * `INT_MAX`, the function returns `INT_MAX`; otherwise it returns `(int) val`.
+ *
+ * **Thread Safety: MT-Safe**
+ * Performs only arithmetic on the provided argument; uses no shared state.
+ *
+ * **Async Signal Safety: AS-Safe**
+ * Contains only simple arithmetic and comparison; safe for use in signal
+ * handlers.
+ *
+ * **Async Cancel Safety: AC-Safe**
+ * Contains no cancellation points.
+ *
+ * @param val The non-negative value to convert.
+ * @return `(int) val` when within range, or `INT_MAX` if capped.
+ */
 int
 cap_size_t_to_int( size_t val );
 

include/private/param.h

@@ -22,6 +22,31 @@
 #  include <stddef.h>
 #  include <stumpless/param.h>
 
+
+/**
+ * Locks the internal mutex of the given parameter.
+ *
+ * Acquires exclusive access to the specified `stumpless_param` so that no
+ * other thread may read or modify it concurrently. This must be paired with
+ * a later call to `unlock_param()` by the same thread. The function does not
+ * perform NULL or ownership checks and should only be used on initialized
+ * parameters.
+ *
+ * **Thread Safety: MT-Safe**
+ * Coordinates concurrent access using the parameter's mutex; only one thread
+ * may hold the lock at a time.
+ *
+ * **Async Signal Safety: AS-Unsafe (lock)**
+ * Not safe to call from signal handlers due to the use of non-reentrant
+ * mutex operations.
+ *
+ * **Async Cancel Safety: AC-Unsafe (lock)**
+ * May block or leave the mutex locked if a thread is asynchronously
+ * cancelled while waiting for the lock.
+ *
+ * @param param The parameter whose internal lock to acquire. Must not be NULL
+ *              and must not already be locked by the same thread.
+ */
 void
 lock_param( const struct stumpless_param *param );
 

include/private/strhelper.h

@@ -28,6 +28,28 @@
  */
 #  define GENERATE_STRING( STRING, INDEX ) #STRING,
 
+/**
+ * Creates a duplicate of the given C-string.
+ *
+ * Allocates a new buffer and copies the contents of `str` into it,
+ * including the terminating NULL byte. The returned string must be freed
+ * with the corresponding deallocator when no longer needed.
+ *
+ * **Thread Safety: MT-Safe**
+ * Uses heap allocation but maintains no shared global state; safe when
+ * used concurrently in multiple threads.
+ *
+ * **Async Signal Safety: AS-Unsafe (heap)**
+ * Not safe to call from signal handlers because it may invoke memory
+ * allocation routines that are not reentrant.
+ *
+ * **Async Cancel Safety: AC-Unsafe (heap)**
+ * May leave heap state inconsistent if a thread is asynchronously
+ * cancelled during allocation.
+ *
+ * @param str The NULL-terminated source string to copy. Must not be NULL.
+ * @return A newly allocated copy of `str`, or `NULL` if allocation fails.
+ */
 char *
 copy_cstring( const char *str );