Miscellaneous documentation fixes

nx/include/switch/arm/atomics.h

@@ -1,18 +1,28 @@
+/**
+ * @file atomics.h
+ * @brief AArch64 atomic operations.
+ * @author plutoo
+ * @copyright libnx Authors
+ */
 #pragma once
 #include "../types.h"
 
+/// Atomically increments a 32-bit value.
 static inline u32 atomicIncrement32(u32* p) {
     return __atomic_fetch_add(p, 1, __ATOMIC_SEQ_CST);
 }
 
+/// Atomically decrements a 32-bit value.
 static inline u32 atomicDecrement32(u32* p) {
     return __atomic_sub_fetch(p, 1, __ATOMIC_SEQ_CST);
 }
 
+/// Atomically increments a 64-bit value.
 static inline u64 atomicIncrement64(u64* p) {
     return __atomic_fetch_add(p, 1, __ATOMIC_SEQ_CST);
 }
 
+/// Atomically decrements a 64-bit value.
 static inline u64 atomicDecrement64(u64* p) {
     return __atomic_sub_fetch(p, 1, __ATOMIC_SEQ_CST);
 }

nx/include/switch/kernel/event.h

@@ -1,13 +1,19 @@
-// Copyright 2018 plutoo
+/**
+ * @file event.h
+ * @brief Kernel-mode event synchronization primitive.
+ * @author plutoo
+ * @copyright libnx Authors
+ */
 #pragma once
 #include "../types.h"
 #include "../result.h"
 #include "wait.h"
 
+/// Kernel-mode event structure.
 typedef struct {
-    Handle revent;
+    Handle revent;  ///< Read-only event handle
-    Handle wevent;
+    Handle wevent;  ///< Write-only event handle
-    bool autoclear;
+    bool autoclear; ///< Autoclear flag
 } Event;
 
 /// Creates a \ref Waiter for a kernel-mode event.
@@ -19,16 +25,60 @@ static inline Waiter waiterForEvent(Event* t)
     return wait_obj;
 }
 
+/**
+ * @brief Creates a kernel-mode event.
+ * @param[out] t Pointer to \ref Event structure.
+ * @param[in] autoclear Autoclear flag.
+ * @return Result code.
+ * @warning This is a privileged operation; in normal circumstances applications shouldn't use this function.
+ */
 Result eventCreate(Event* t, bool autoclear);
+
+/**
+ * @brief Loads a kernel-mode event obtained from IPC.
+ * @param[out] t Pointer to \ref Event structure.
+ * @param[in] handle Read-only event handle.
+ * @param[in] autoclear Autoclear flag.
+ */
 void   eventLoadRemote(Event* t, Handle handle, bool autoclear);
+
+/**
+ * @brief Closes a kernel-mode event.
+ * @param[in] t Pointer to \ref Event structure.
+ */
 void   eventClose(Event* t);
 
-/// Returns whether the Event is initialized.
+/**
+ * @brief Returns whether an \ref Event is initialized.
+ * @param[in] t Pointer to \ref Event structure.
+ * @return Initialization status.
+ */
 static inline bool eventActive(Event* t)
 {
     return t->revent != INVALID_HANDLE;
 }
 
+/**
+ * @brief Waits on a kernel-mode event.
+ * @param[in] t Pointer to \ref Event structure.
+ * @param[in] timeout Timeout in nanoseconds (pass UINT64_MAX to wait indefinitely).
+ * @return Result code.
+ */
 Result eventWait(Event* t, u64 timeout);
+
+/**
+ * @brief Signals a kernel-mode event.
+ * @param[in] t Pointer to \ref Event structure.
+ * @return Result code.
+ * @note This function only works for events initialized with \ref eventCreate, it doesn't work with events initialized with \ref eventLoadRemote.
+ * @warning This is a privileged operation; in normal circumstances applications shouldn't use this function.
+ */
 Result eventFire(Event* t);
+
+/**
+ * @brief Clears a kernel-mode event.
+ * @param[in] t Pointer to \ref Event structure.
+ * @return Result code.
+ * @note This function shouldn't be used on autoclear events.
+ */
 Result eventClear(Event* t);

nx/include/switch/runtime/nxlink.h

@@ -1,10 +1,22 @@
+/**
+ * @file nxlink.h
+ * @brief Netloader (nxlink) utilities
+ * @author WinterMute
+ * @copyright libnx Authors
+ */
 #pragma once
 
 struct in_addr;
 
+/// Address of the host connected through nxlink
 extern struct in_addr __nxlink_host;
 
-#define NXLINK_SERVER_PORT 28280
+#define NXLINK_SERVER_PORT 28280 ///< nxlink TCP server port
-#define NXLINK_CLIENT_PORT 28771
+#define NXLINK_CLIENT_PORT 28771 ///< nxlink TCP client port
 
+/**
+ * @brief Sets up stdout/stderr redirection to the nxlink host.
+ * @return Socket fd on success, negative number on failure.
+ * @note The socket should be closed with close() during application cleanup.
+ */
 int nxlinkStdio(void);

nx/include/switch/services/gpio.h

@@ -1,6 +1,6 @@
 /**
- * @file i2c.h
+ * @file gpio.h
- * @brief I2C service IPC wrapper.
+ * @brief GPIO service IPC wrapper.
  * @author SciresM
  * @copyright libnx Authors
  */