add doxygen for exported functions in jlapi.c (#52324)

This adds some brief doxygen-formatted docstrings to jlapi.c.
The objective of this PR is to set doxygen docstrings as the
documentation method for Julia's C code, and allow for
further development of reference material for the use
of Julia through the C API.

These docstrings are immediately useful for consumption by
C/C++ development extensions such as tooltips.
In the future these can be useful to generate a cohesive API reference,
though this is a separate concern involving the build system.

src/jl_uv.c

@@ -136,11 +136,17 @@ void JL_UV_LOCK(void)
     }
 }
 
+/**
+ * @brief Begin an IO lock.
+ */
 JL_DLLEXPORT void jl_iolock_begin(void)
 {
     JL_UV_LOCK();
 }
 
+/**
+ * @brief End an IO lock.
+ */
 JL_DLLEXPORT void jl_iolock_end(void)
 {
     JL_UV_UNLOCK();
@@ -227,9 +233,16 @@ static void uv_flush_callback(uv_write_t *req, int status)
     free(req);
 }
 
-// Turn a normal write into a blocking write (primarily for use from C and gdb).
-// Warning: This calls uv_run, so it can have unbounded side-effects.
-// Be care where you call it from! - the libuv loop is also not reentrant.
+/**
+ * @brief Flush a UV stream.
+ *
+ * Primarily used from C and gdb to convert a normal write operation on a UV stream
+ * into a blocking write. It calls uv_run, which can have unbounded side-effects.
+ * Caution is advised as the location from where this function is called is critical
+ * due to the non-reentrancy of the libuv loop.
+ *
+ * @param stream A pointer to `uv_stream_t` representing the stream to flush.
+ */
 JL_DLLEXPORT void jl_uv_flush(uv_stream_t *stream)
 {
     if (stream == (void*)STDIN_FILENO ||
@@ -261,21 +274,111 @@ JL_DLLEXPORT void jl_uv_flush(uv_stream_t *stream)
 
 // getters and setters
 // TODO: check if whoever calls these is thread-safe
+/**
+ * @brief Get the process ID of a UV process.
+ *
+ * @param p A pointer to `uv_process_t` representing the UV process.
+ * @return The process ID.
+ */
 JL_DLLEXPORT int jl_uv_process_pid(uv_process_t *p) { return p->pid; }
+
+/**
+ * @brief Get the data associated with a UV process.
+ *
+ * @param p A pointer to `uv_process_t` representing the UV process.
+ * @return A pointer to the process data.
+ */
 JL_DLLEXPORT void *jl_uv_process_data(uv_process_t *p) { return p->data; }
+
+/**
+ * @brief Get the base pointer of a UV buffer.
+ *
+ * @param buf A constant pointer to `uv_buf_t` representing the UV buffer.
+ * @return A pointer to the base of the buffer.
+ */
 JL_DLLEXPORT void *jl_uv_buf_base(const uv_buf_t *buf) { return buf->base; }
+
+/**
+ * @brief Get the length of a UV buffer.
+ *
+ * @param buf A constant pointer to `uv_buf_t` representing the UV buffer.
+ * @return The length of the buffer as `size_t`.
+ */
 JL_DLLEXPORT size_t jl_uv_buf_len(const uv_buf_t *buf) { return buf->len; }
+
+/**
+ * @brief Set the base pointer of a UV buffer.
+ *
+ * @param buf A pointer to `uv_buf_t` representing the UV buffer.
+ * @param b A pointer to `char` representing the new base of the buffer.
+ */
 JL_DLLEXPORT void jl_uv_buf_set_base(uv_buf_t *buf, char *b) { buf->base = b; }
+
+/**
+ * @brief Set the length of a UV buffer.
+ *
+ * @param buf A pointer to `uv_buf_t` representing the UV buffer.
+ * @param n The new length of the buffer as `size_t`.
+ */
 JL_DLLEXPORT void jl_uv_buf_set_len(uv_buf_t *buf, size_t n) { buf->len = n; }
+
+/**
+ * @brief Get the handle associated with a UV connect request.
+ *
+ * @param connect A pointer to `uv_connect_t` representing the connect request.
+ * @return A pointer to the associated handle.
+ */
 JL_DLLEXPORT void *jl_uv_connect_handle(uv_connect_t *connect) { return connect->handle; }
+
+/**
+ * @brief Get the file descriptor from a UV file structure.
+ *
+ * @param f A pointer to `jl_uv_file_t` representing the UV file.
+ * @return The file descriptor as `uv_os_fd_t`.
+ */
 JL_DLLEXPORT uv_os_fd_t jl_uv_file_handle(jl_uv_file_t *f) { return f->file; }
+
+/**
+ * @brief Get the data field from a UV request.
+ *
+ * @param req A pointer to `uv_req_t` representing the request.
+ * @return A pointer to the data associated with the request.
+ */
 JL_DLLEXPORT void *jl_uv_req_data(uv_req_t *req) { return req->data; }
+
+/**
+ * @brief Set the data field of a UV request.
+ *
+ * @param req A pointer to `uv_req_t` representing the request.
+ * @param data A pointer to the data to be associated with the request.
+ */
 JL_DLLEXPORT void jl_uv_req_set_data(uv_req_t *req, void *data) { req->data = data; }
+
+/**
+ * @brief Get the data field from a UV handle.
+ *
+ * @param handle A pointer to `uv_handle_t` representing the handle.
+ * @return A pointer to the data associated with the handle.
+ */
 JL_DLLEXPORT void *jl_uv_handle_data(uv_handle_t *handle) { return handle->data; }
+
+/**
+ * @brief Get the handle associated with a UV write request.
+ *
+ * @param req A pointer to `uv_write_t` representing the write request.
+ * @return A pointer to the handle associated with the write request.
+ */
 JL_DLLEXPORT void *jl_uv_write_handle(uv_write_t *req) { return req->handle; }
 
 extern _Atomic(unsigned) _threadedregion;
 
+/**
+ * @brief Process pending UV events.
+ *
+ * See also `uv_run` in the libuv documentation for status code enumeration.
+ *
+ * @return An integer indicating the status of the event processing.
+ */
 JL_DLLEXPORT int jl_process_events(void)
 {
     jl_task_t *ct = jl_current_task;
@@ -302,6 +405,11 @@ static void jl_proc_exit_cleanup_cb(uv_process_t *process, int64_t exit_status,
     uv_close((uv_handle_t*)process, (uv_close_cb)&free);
 }
 
+/**
+ * @brief Close a UV handle.
+ *
+ * @param handle A pointer to `uv_handle_t` that needs to be closed.
+ */
 JL_DLLEXPORT void jl_close_uv(uv_handle_t *handle)
 {
     JL_UV_LOCK();
@@ -335,6 +443,11 @@ JL_DLLEXPORT void jl_close_uv(uv_handle_t *handle)
     JL_UV_UNLOCK();
 }
 
+/**
+ * @brief Forcefully close a UV handle.
+ *
+ * @param handle A pointer to `uv_handle_t` to be forcefully closed.
+ */
 JL_DLLEXPORT void jl_forceclose_uv(uv_handle_t *handle)
 {
     if (!uv_is_closing(handle)) { // avoid double-closing the stream
@@ -346,19 +459,53 @@ JL_DLLEXPORT void jl_forceclose_uv(uv_handle_t *handle)
     }
 }
 
+/**
+ * @brief Associate a Julia structure with a UV handle.
+ *
+ * @param handle A pointer to `uv_handle_t` to be associated with a Julia structure.
+ * @param data Additional parameters representing the Julia structure to be associated.
+ */
 JL_DLLEXPORT void jl_uv_associate_julia_struct(uv_handle_t *handle,
                                                jl_value_t *data)
 {
     handle->data = data;
 }
 
+/**
+ * @brief Disassociate a Julia structure from a UV handle.
+ *
+ * @param handle A pointer to `uv_handle_t` from which the Julia structure will be disassociated.
+ */
 JL_DLLEXPORT void jl_uv_disassociate_julia_struct(uv_handle_t *handle)
 {
     handle->data = NULL;
 }
 
 #define UV_HANDLE_CLOSED 0x02
 
+/**
+ * @brief Spawn a new process.
+ *
+ * Spawns a new process to execute external programs or scripts within the context of the Julia application.
+ *
+ * @param name A C string representing the name or path of the executable to spawn.
+ * @param argv An array of C strings representing the arguments for the process. The array should be null-terminated.
+ * @param loop A pointer to `uv_loop_t` representing the event loop where the process is registered.
+ * @param proc A pointer to `uv_process_t` where the details of the spawned process are stored.
+ * @param stdio An array of `uv_stdio_container_t` representing the file descriptors for standard input, output, and error.
+ * @param nstdio An integer representing the number of elements in the stdio array.
+ * @param flags A uint32_t representing process creation flags.
+          See also `enum uv_process_flags` in the libuv documentation.
+ * @param env An array of C strings for setting environment variables. The array should be null-terminated.
+ * @param cwd A C string representing the current working directory for the process.
+ * @param cpumask A C string representing the CPU affinity mask for the process.
+          See also the `cpumask` field of the `uv_process_options_t` structure in the libuv documentation.
+ * @param cpumask_size The size of the cpumask.
+ * @param cb A function pointer to `uv_exit_cb` which is the callback function to be called upon process exit.
+ *
+ * @return An integer indicating the success or failure of the spawn operation. A return value of 0 indicates success,
+ *         while a non-zero value indicates an error.
+ */
 JL_DLLEXPORT int jl_spawn(char *name, char **argv,
                           uv_loop_t *loop, uv_process_t *proc,
                           uv_stdio_container_t *stdio, int nstdio,