Fixed doxygen issues / improved docs. Closes #230.

nx/include/switch/applets/swkbd.h

@@ -8,6 +8,7 @@
 #include "../types.h"
 #include "../services/applet.h"
 
+/// Output result returned by \ref SwkbdTextCheckCb.
 typedef enum {
     SwkbdTextCheckResult_OK      = 0,  ///< Success, valid string.
     SwkbdTextCheckResult_Bad     = 1,  ///< Failure, invalid string. Error message is displayed in a message-box, pressing OK will return to swkbd again.
@@ -15,6 +16,7 @@ typedef enum {
     SwkbdTextCheckResult_Silent  = 3,  ///< Failure, invalid string. With value 3 and above, swkbd will silently not accept the string, without displaying any error.
 } SwkbdTextCheckResult;
 
+/// Type of keyboard.
 typedef enum {
     SwkbdType_Normal = 0,  ///< Normal keyboard.
     SwkbdType_NumPad = 1,  ///< Number pad. The buttons at the bottom left/right are only available when they're set by \ref swkbdConfigSetLeftOptionalSymbolKey / \ref swkbdConfigSetRightOptionalSymbolKey.
@@ -66,7 +68,7 @@ typedef enum {
 /// SwkbdInline State
 typedef enum {
     SwkbdState_Inactive       = 0x0,  ///< Default state from \ref swkbdInlineCreate, before a state is set by \ref swkbdInlineUpdate when a reply is received. Also indicates that the applet is no longer running.
-    SwkbdState_Initialized    = 0x1,
+    SwkbdState_Initialized    = 0x1,  ///< Applet is initialized.
     SwkbdState_Unknown2       = 0x2,
     SwkbdState_TextAvailable  = 0x3,  ///< Text is available since a ChangedString* reply was received.
     SwkbdState_Submitted      = 0x4,  ///< The user pressed the ok-button, submitting the text and closing the applet.
@@ -479,7 +481,6 @@ void swkbdInlineDisappear(SwkbdInline* s);
  * @brief Creates a \ref SwkbdAppearArg which can then be passed to \ref swkbdInlineAppear. arg is initialized with the defaults, with type being set to the input type.
  * @param arg Output \ref SwkbdAppearArg.
  * @param type \ref SwkbdType type
- * @param str Input UTF-8 string for the Ok button text, this can be empty/NULL to use the default.
  */
 void swkbdInlineMakeAppearArg(SwkbdAppearArg* arg, SwkbdType type);
 
@@ -498,7 +499,7 @@ void swkbdInlineAppearArgSetOkButtonText(SwkbdAppearArg* arg,  const char* str);
 void swkbdInlineAppearArgSetLeftButtonText(SwkbdAppearArg* arg, const char* str);
 
 /**
- * @brief Sets the RightButtonText, for \ref SwkbdType_NumPad. The default is "". Equivalent to \ref sswkbdConfigSetRightOptionalSymbolKey.
+ * @brief Sets the RightButtonText, for \ref SwkbdType_NumPad. The default is "". Equivalent to \ref swkbdConfigSetRightOptionalSymbolKey.
  * @param arg \ref SwkbdAppearArg, previously initialized by \ref swkbdInlineMakeAppearArg.
  * @param str UTF-8 input string.
  */
@@ -531,7 +532,7 @@ void swkbdInlineSetCursorPos(SwkbdInline* s, s32 pos);
 
 /**
  * @brief Sets the UserWordInfo.
- * @note Not avilable when \ref SwkbdState is above \ref SwkbdState_Initialized. Can't be used if this was already used previously.
+ * @note Not avilable when \ref SwkbdState is above ::SwkbdState_Initialized. Can't be used if this was already used previously.
  * @note The specified buffer must not be used after this, until \ref swkbdInlineClose is used.
  * @note \ref swkbdInlineUpdate must be called at some point afterwards.
  * @note If input==NULL or total_entries==0, this will just call \ref swkbdInlineUnsetUserWordInfo internally.
@@ -544,7 +545,7 @@ Result swkbdInlineSetUserWordInfo(SwkbdInline* s, const SwkbdDictWord *input, s3
 /**
  * @brief Request UnsetUserWordInfo.
  * @note \ref swkbdInlineUpdate must be called at some point afterwards for this to take affect.
- * @note Not avilable when \ref SwkbdState is above \ref SwkbdState_Initialized.
+ * @note Not avilable when \ref SwkbdState is above ::SwkbdState_Initialized.
  * @param s SwkbdInline object.
  */
 Result swkbdInlineUnsetUserWordInfo(SwkbdInline* s);
@@ -560,7 +561,7 @@ void swkbdInlineSetUtf8Mode(SwkbdInline* s, bool flag);
 
 /**
  * @brief Sets the CustomizeDic.
- * @note Not avilable when \ref SwkbdState is above \ref SwkbdState_Initialized. Can't be used if this was already used previously.
+ * @note Not avilable when \ref SwkbdState is above ::SwkbdState_Initialized. Can't be used if this was already used previously.
  * @note The specified buffer must not be used after this, until \ref swkbdInlineClose is used. However, it will also become available once \ref swkbdInlineUpdate handles SwkbdReplyType_UnsetCustomizeDic internally.
  * @param s SwkbdInline object.
  * @param buffer 0x1000-byte aligned buffer.
@@ -572,7 +573,7 @@ Result swkbdInlineSetCustomizeDic(SwkbdInline* s, void* buffer, size_t size, Swk
 /**
  * @brief Request UnsetCustomizeDic.
  * @note \ref swkbdInlineUpdate must be called at some point afterwards for this to take affect.
- * @note Not avilable when \ref SwkbdState is above \ref SwkbdState_Initialized.
+ * @note Not avilable when \ref SwkbdState is above ::SwkbdState_Initialized.
  * @param s SwkbdInline object.
  */
 void swkbdInlineUnsetCustomizeDic(SwkbdInline* s);

nx/include/switch/display/types.h

@@ -1,5 +1,5 @@
 /**
- * @file types.h
+ * @file display/types.h
  * @brief Definitions for Android-related types and enumerations.
  * @copyright libnx Authors
  */

nx/include/switch/kernel/ipc.h

@@ -401,7 +401,7 @@ typedef struct {
 
 /**
  * @brief Parse an IPC command response into an IPC parsed command structure.
- * @param IPC parsed command structure to fill in.
+ * @param r IPC parsed command structure to fill in.
  * @return Result code.
  */
 static inline Result ipcParse(IpcParsedCommand* r) {
@@ -648,7 +648,7 @@ static inline void ipcSendObjectId(IpcCommand* cmd, u32 object_id) {
  * @brief Prepares the header of an IPC command structure (domain version).
  * @param cmd IPC command structure.
  * @param sizeof_raw Size in bytes of the raw data structure to embed inside the IPC request
- * @oaram object_id Domain object ID.
+ * @param object_id Domain object ID.
  * @return Pointer to the raw embedded data structure in the request, ready to be filled out.
  */
 static inline void* ipcPrepareHeaderForDomain(IpcCommand* cmd, size_t sizeof_raw, u32 object_id) {
@@ -669,7 +669,7 @@ static inline void* ipcPrepareHeaderForDomain(IpcCommand* cmd, size_t sizeof_raw
 
 /**
  * @brief Parse an IPC command request into an IPC parsed command structure (domain version).
- * @param IPC parsed command structure to fill in.
+ * @param r IPC parsed command structure to fill in.
  * @return Result code.
  */
 static inline Result ipcParseDomainRequest(IpcParsedCommand* r) {
@@ -706,7 +706,8 @@ static inline Result ipcParseDomainRequest(IpcParsedCommand* r) {
 
 /**
  * @brief Parse an IPC command response into an IPC parsed command structure (domain version).
- * @param IPC parsed command structure to fill in.
+ * @param r IPC parsed command structure to fill in.
+ * @param sizeof_raw Size in bytes of the raw data structure.
  * @return Result code.
  */
 static inline Result ipcParseDomainResponse(IpcParsedCommand* r, size_t sizeof_raw) {

nx/include/switch/kernel/svc.h

@@ -204,7 +204,7 @@ Result svcUnmapMemory(void* dst_addr, void* src_addr, u64 size);
 /**
  * @brief Query information about an address. Will always fetch the lowest page-aligned mapping that contains the provided address.
  * @param[out] meminfo_ptr \ref MemoryInfo structure which will be filled in.
- * @param[out] page_info Page information which will be filled in.
+ * @param[out] pageinfo Page information which will be filled in.
  * @param[in] addr Address to query.
  * @return Result code.
  * @note Syscall number 0x06.
@@ -868,7 +868,7 @@ Result svcGetDebugEvent(u8* event_out, Handle debug);
  * @return Result code.
  * @note Syscall number 0x64.
  * @warning This is a privileged syscall. Use \ref envIsSyscallHinted to check if it is available.
- * @warning Only exists on 3.0.0+. For older versions use \ref svcContinueDebugEventPre300.
+ * @warning Only exists on 3.0.0+. For older versions use \ref svcLegacyContinueDebugEvent.
  */
 Result svcContinueDebugEvent(Handle debug, u32 flags, u64* tid_list, u32 num_tids);
 
@@ -886,7 +886,7 @@ Result svcLegacyContinueDebugEvent(Handle debug, u32 flags, u64 threadID);
  * @return Result code.
  * @param[out] ctx Output thread context (register dump).
  * @param[in] debug Debug handle.
- * @param[in] threadId ID of the thread to dump the context of.
+ * @param[in] threadID ID of the thread to dump the context of.
  * @param[in] flags Register groups to select, combination of @ref RegisterGroup flags.
  * @note Syscall number 0x67.
  * @warning Official kernel will not dump any CPU GPR if the thread is currently executing a system call (except @ref svcBreak and @ref svcReturnFromException).
@@ -898,7 +898,7 @@ Result svcGetDebugThreadContext(ThreadContext* ctx, Handle debug, u64 threadID,
  * @brief Gets the context (dump the registers) of a thread in a debugging session.
  * @return Result code.
  * @param[in] debug Debug handle.
- * @param[in] threadId ID of the thread to set the context of.
+ * @param[in] threadID ID of the thread to set the context of.
  * @param[in] ctx Input thread context (register dump).
  * @param[in] flags Register groups to select, combination of @ref RegisterGroup flags.
  * @note Syscall number 0x68.

nx/include/switch/kernel/uevent.h

@@ -28,7 +28,7 @@ static inline Waiter waiterForUEvent(UEvent* e)
 /**
  * @brief Creates a user-mode event.
  * @param[out] e UEvent object.
- * @param[in] bool auto_clear Whether to automatically clear the event.
+ * @param[in] auto_clear Whether to automatically clear the event.
  * @note It is safe to wait on this event with several threads simultaneously.
  * @note If more than one thread is listening on it, at least one thread will get the signal. No other guarantees.
  */

nx/include/switch/services/applet.h

@@ -82,10 +82,10 @@ typedef enum {
 
 /// LibraryAppletMode
 typedef enum {
-    LibAppletMode_AllForeground = 0,
-    LibAppletMode_Background = 1,
-    LibAppletMode_Unknown2 = 2,
-    LibAppletMode_Unknown3 = 3,
+    LibAppletMode_AllForeground = 0,  ///< Foreground
+    LibAppletMode_Background = 1,     ///< Background
+    LibAppletMode_Unknown2 = 2,       ///< Unknown
+    LibAppletMode_Unknown3 = 3,       ///< Unknown
 } LibAppletMode;
 
 /// LibraryAppletExitReason
@@ -96,6 +96,7 @@ typedef enum {
     LibAppletExitReason_Unexpected = 10,
 } LibAppletExitReason;
 
+/// ThemeColorType
 typedef enum {
     AppletThemeColorType_Default = 0,
     AppletThemeColorType_Unknown1 = 1,
@@ -138,8 +139,12 @@ typedef struct {
     u8 unk_x0[0x8];
 } AppletApplicationPlayStatistics;
 
+/// Initialize applet, called automatically during app startup.
 Result appletInitialize(void);
+
+/// Exit applet, called automatically during app startup.
 void appletExit(void);
+
 Result appletGetAppletResourceUserId(u64 *out);
 AppletType appletGetAppletType(void);
 
@@ -212,6 +217,8 @@ Result appletQueryApplicationPlayStatistics(AppletApplicationPlayStatistics *sta
  * @note \ref appletUnlockExit must be used before main() returns.
  */
 Result appletLockExit(void);
+
+/// Unlocks exiting, see \ref appletLockExit.
 Result appletUnlockExit(void);
 
 /**
@@ -255,7 +262,7 @@ bool appletHolderActive(AppletHolder *h);
 
 /**
  * @brief Gets the IndirectLayerConsumerHandle loaded during \ref appletCreateLibraryApplet, on 2.0.0+.
- * @note  Only available when \ref LibAppletMode is \ref LibAppletMode_Unknown3.
+ * @note  Only available when \ref LibAppletMode is ::LibAppletMode_Unknown3.
  * @param h AppletHolder object.
  * @param out Output IndirectLayerConsumerHandle.
  */
@@ -395,6 +402,7 @@ Result appletStorageRead(AppletStorage *s, s64 offset, void* buffer, size_t size
 /**
  * @brief Gets data for a HandleStorage originally from \ref appletCreateHandleStorage input.
  * @note  Only available on 2.0.0+.
+ * @param s Storage object.
  * @param out Output value.
  * @param handle Output handle.
  */

nx/include/switch/services/audin.h

@@ -33,7 +33,10 @@ Result audinOpenAudioIn(const char *DeviceNameIn, char *DeviceNameOut, u32 Sampl
 Result audinGetAudioInState(AudioInState *State);
 Result audinStartAudioIn(void);
 Result audinStopAudioIn(void);
+
+/// Submits an \ref AudioInBuffer for capturing.
 Result audinAppendAudioInBuffer(AudioInBuffer *Buffer);
+
 Result audinGetReleasedAudioInBuffer(AudioInBuffer **Buffer, u32 *ReleasedBuffersCount);
 Result audinContainsAudioInBuffer(AudioInBuffer *Buffer, bool *ContainsBuffer);
 

nx/include/switch/services/audout.h

@@ -33,7 +33,10 @@ Result audoutOpenAudioOut(const char *DeviceNameIn, char *DeviceNameOut, u32 Sam
 Result audoutGetAudioOutState(AudioOutState *State);
 Result audoutStartAudioOut(void);
 Result audoutStopAudioOut(void);
+
+/// Submits an \ref AudioOutBuffer for playing.
 Result audoutAppendAudioOutBuffer(AudioOutBuffer *Buffer);
+
 Result audoutGetReleasedAudioOutBuffer(AudioOutBuffer **Buffer, u32 *ReleasedBuffersCount);
 Result audoutContainsAudioOutBuffer(AudioOutBuffer *Buffer, bool *ContainsBuffer);
 

nx/include/switch/services/bsd.h

@@ -38,6 +38,7 @@ Result bsdInitialize(const BsdInitConfig *config);
 /// Deinitialize the BSD service.
 void bsdExit(void);
 
+/// Creates a socket.
 int bsdSocket(int domain, int type, int protocol);
 /// Like @ref bsdSocket but the newly created socket is immediately shut down.
 int bsdSocketExempt(int domain, int type, int protocol);

nx/include/switch/services/fatal.h

@@ -75,7 +75,7 @@ typedef struct {
 
 /**
  * @brief Triggers a system fatal error.
- * @param err[in] Result code to throw.
+ * @param[in] err Result code to throw.
  * @note This function does not return.
  * @note This uses \ref fatalWithType with \ref FatalType_ErrorScreen internally.
  */
@@ -83,17 +83,17 @@ void NORETURN fatalSimple(Result err);
 
 /**
  * @brief Triggers a system fatal error with a custom \ref FatalType.
- * @param err[in] Result code to throw.
- * @param type[in] Type of fatal error to throw.
+ * @param[in] err Result code to throw.
+ * @param[in] type Type of fatal error to throw.
  * @note This function may not return, depending on \ref FatalType.
  */
 void fatalWithType(Result err, FatalType type);
 
 /**
  * @brief Triggers a system fatal error with a custom \ref FatalType and \ref FatalContext.
- * @param err[in]  Result code to throw.
- * @param type[in] Type of fatal error to throw.
- * @param ctx[in]  Cpu context for fatal error to throw.
+ * @param[in] err  Result code to throw.
+ * @param[in] type Type of fatal error to throw.
+ * @param[in] ctx  Cpu context for fatal error to throw.
  * @note This function may not return, depending on \ref FatalType.
  */
 void fatalWithContext(Result err, FatalType type, FatalContext *ctx);

nx/include/switch/services/hid.h

@@ -214,6 +214,7 @@ typedef enum
     KBD_MEDIA_CALC = 0xfb
 } HidKeyboardScancode;
 
+/// HID controller type
 typedef enum
 {
     TYPE_PROCONTROLLER = BIT(0),
@@ -231,7 +232,7 @@ typedef enum
     LAYOUT_LEFT            = 3, ///< Only single-mode raw left Joy-Con state, no orientation adjustment.
     LAYOUT_RIGHT           = 4, ///< Only single-mode raw right Joy-Con state, no orientation adjustment.
     LAYOUT_DEFAULT_DIGITAL = 5, ///< Same as next, but sticks have 8-direction values only.
-    LAYOUT_DEFAULT         = 6, ///< Safe default. Single-mode and \ref HidJoyHoldType_Horizontal: Joy-Con have buttons/sticks rotated for orientation, where physical Z(L/R) are unavailable and S(L/R) are mapped to L/R (with physical L/R unavailable).
+    LAYOUT_DEFAULT         = 6, ///< Safe default. Single-mode and ::HidJoyHoldType_Horizontal: Joy-Con have buttons/sticks rotated for orientation, where physical Z(L/R) are unavailable and S(L/R) are mapped to L/R (with physical L/R unavailable).
 } HidControllerLayoutType;
 
 typedef enum
@@ -612,6 +613,7 @@ static inline HidControllerID hidControllerIDFromOfficial(u32 id) {
     return CONTROLLER_UNKNOWN;
 }
 
+/// Initializes hid, called automatically during app startup.
 Result hidInitialize(void);
 void hidExit(void);
 void hidReset(void);
@@ -621,6 +623,7 @@ void* hidGetSharedmemAddr(void);
 
 void hidSetControllerLayout(HidControllerID id, HidControllerLayoutType layoutType);
 HidControllerLayoutType hidGetControllerLayout(HidControllerID id);
+/// Gets the \ref HidControllerType for the specified controller.
 HidControllerType hidGetControllerType(HidControllerID id);
 void hidGetControllerColors(HidControllerID id, HidControllerColors *colors);
 bool hidIsControllerConnected(HidControllerID id);

nx/include/switch/services/hwopus.h

@@ -38,5 +38,6 @@ void hwopusDecoderExit(HwopusDecoder* decoder);
 /// See libopus multistream docs.
 Result hwopusDecoderMultistreamInitialize(HwopusDecoder* decoder, s32 SampleRate, s32 ChannelCount, s32 TotalStreamCount, s32 StereoStreamCount, u8 *channel_mapping);
 
+/// Decodes opus data.
 Result hwopusDecodeInterleaved(HwopusDecoder* decoder, s32 *DecodedDataSize, s32 *DecodedSampleCount, const void* opusin, size_t opusin_size, s16 *pcmbuf, size_t pcmbuf_size);
 

nx/include/switch/services/irs.h

@@ -49,13 +49,16 @@ typedef struct {
     u8 unk_x0[0x10];
 } PACKED IrsImageTransferProcessorState;
 
+/// Initialize irs.
 Result irsInitialize(void);
+
+/// Exit irs.
 void irsExit(void);
 
 Service* irsGetSessionService(void);
 void* irsGetSharedmemAddr(void);
 
-/// (De)activate the IR sensor, this is automatically used by irsExit(). Must be called after irsInitialize() to activate the IR sensor.
+/// (De)activate the IR sensor, this is automatically used by \ref irsExit. Must be called after irsInitialize() to activate the IR sensor.
 Result irsActivateIrsensor(bool activate);
 
 Result irsGetIrCameraHandle(u32 *IrCameraHandle, HidControllerID id);

nx/include/switch/services/psm.h

@@ -39,6 +39,7 @@ Result psmGetBatteryVoltageState(PsmBatteryVoltageState *out);
  * @brief Wrapper func which opens a PsmSession and handles event setup.
  * @note Uses the actual BindStateChangeEvent cmd internally.
  * @note The event is not signalled on BatteryChargePercentage changes.
+ * @param[out] s PsmSession object.
  * @param[in] ChargerType Passed to SetChargerTypeChangeEventEnabled.
  * @param[in] PowerSupply Passed to SetPowerSupplyChangeEventEnabled.
  * @param[in] BatteryVoltage Passed to SetBatteryVoltageStateChangeEventEnabled.

nx/include/switch/services/set.h

@@ -122,13 +122,18 @@ Result setsysSetColorSetId(ColorSetId id);
 
 /**
  * @brief Gets the size of a settings item value.
- * @param out Pointer to output the size to.
+ * @param name Name string.
+ * @param item_key Item key string.
+ * @param size_out Pointer to output the size to.
  */
 Result setsysGetSettingsItemValueSize(const char *name, const char *item_key, u64 *size_out);
 
 /**
  * @brief Gets the value of a settings item.
- * @param out Pointer to output the value to.
+ * @param name Name string.
+ * @param item_key Item key string.
+ * @param value_out Pointer to output the value to.
+ * @param value_out_size Size of the value_out buffer.
  */
 Result setsysGetSettingsItemValue(const char *name, const char *item_key, void *value_out, size_t value_out_size);
 
@@ -167,6 +172,6 @@ Result setsysBindFatalDirtyFlagEvent(Event *out);
 /**
  * @brief Gets the settings flags that have changed.
  * @param flags_0 Pointer to populate with first 64 flags.
- * @param flags_0 Pointer to populate with second 64 flags.
+ * @param flags_1 Pointer to populate with second 64 flags.
  */
 Result setsysGetFatalDirtyFlags(u64 *flags_0, u64 *flags_1);

nx/include/switch/services/sm.h

@@ -209,6 +209,7 @@ static inline void* serviceIpcPrepareHeader(Service* s, IpcCommand* cmd, size_t
  * @brief Parse an IPC command response into an IPC parsed command structure for a service.
  * @param s Service to prepare message header for
  * @param r IPC parsed command structure to fill in.
+ * @param sizeof_raw Size in bytes of the raw data structure.
  * @return Result code.
  */
 static inline Result serviceIpcParse(Service* s, IpcParsedCommand* r, size_t sizeof_raw) {

nx/include/switch/services/usbhs.h

@@ -1,5 +1,5 @@
 /**
- * @file usb.h
+ * @file usbhs.h
  * @brief USB (usb:hs) devices service IPC wrapper.
  * @author yellows8
  * @copyright libnx Authors

nx/include/switch/types.h

@@ -1,5 +1,5 @@
 /**
- * @file types.h
+ * @file switch/types.h
  * @brief Various system types.
  * @copyright libnx Authors
  */