Correct various doxygen warnings/issues.

In a few files group end markers were missing, in a few special
characters needed escaping, and others had incorrect names in
the doc vs the actual code.

Author: QuzarDC

include/kos/cdefs.h

@@ -31,7 +31,7 @@
 #   warning Your GCC is too old. This will probably not work right.
 #endif
 
-/** \defgroup system_attributes
+/** \defgroup system_attributes Function Attribute Defines
     \brief                      Definitions for builtin attributes and compiler directives
     \ingroup                    system
 
@@ -173,7 +173,7 @@
 
 /** @} */
 
-/** \defgroup system_compat
+/** \defgroup system_compat Language Compatibility Defines
     \brief                      Definitions for language features
     \ingroup                    system
 
@@ -206,7 +206,7 @@
 
 /** @} */
 
-/** \defgroup system_helpers
+/** \defgroup system_helpers Helper Macros
     \brief                      General useful language macros
     \ingroup                    system
 
@@ -222,7 +222,7 @@
     by the compiler. This can only be used within a function.
 
     Example:
-    #include <stddef.h>
+    \#include <stddef.h>
     ...
     static char *foo_to_char(struct foo *foo)
     {
@@ -244,7 +244,7 @@
     by the compiler. This can be used in an expression: its value is "0".
 
     Example:
-    #define foo_to_char(foo)                \
+    \#define foo_to_char(foo)                \
         ((char *)(foo)                      \
         + __build_assert_or_zero(offsetof(struct foo, string) == 0))
 

kernel/arch/dreamcast/include/arch/irq.h

@@ -1,13 +1,13 @@
 /* KallistiOS ##version##
 
-   arch/dreamcast/include/irq.h
+   arch/dreamcast/include/arch/irq.h
    Copyright (C) 2000-2001 Megan Potter
    Copyright (C) 2024 Paul Cercueil
    Copyright (C) 2024 Falco Girgis
 
 */
 
-/** \file
+/** \file    arch/irq.h
     \brief   Interrupt and exception handling.
     \ingroup irqs
 
@@ -57,7 +57,7 @@ __BEGIN_DECLS
     @{
 */
 
-/** \defgroup Context
+/** \defgroup irq_context Context
     \brief Thread execution state and accessors
 
     This API includes the structure and accessors for a
@@ -437,7 +437,7 @@ typedef struct irq_cb {
     Passing a NULL value for hnd will remove the current handler, if any.
 
     \param  code            The IRQ type to set the handler for
-                            (see \ref irq_exception_codes).
+                            (see #irq_t).
     \param  hnd             A pointer to a procedure to handle the exception.
     \param  data            A pointer that will be passed along to the callback.
     
@@ -480,7 +480,7 @@ irq_cb_t irq_get_handler(irq_t code);
     \retval 0               On success (no error conditions defined).
 
 */
-int irq_set_global_handler(irq_handler handler, void *data);
+int irq_set_global_handler(irq_handler hnd, void *data);
 
 /** Get the global exception handler.
 

kernel/arch/dreamcast/include/arch/trap.h

@@ -5,7 +5,7 @@
 
 */
 
-/** \file    
+/** \file    arch/trap.h
     \brief   Interrupt and exception handling.
     \ingroup traps
 
@@ -59,23 +59,23 @@ typedef uint8_t trapa_t;
 
 /** The type of a TRAPA handler
 
-    \param  trap            The IRQ that caused the handler to be called.
+    \param  code            The IRQ that caused the handler to be called.
     \param  context         The CPU's context.
     \param  data            Arbitrary userdata associated with the handler.
 */
-typedef void (*trapa_handler)(trapa_t trap, irq_context_t *context, void *data);
+typedef void (*trapa_handler)(trapa_t code, irq_context_t *context, void *data);
 
 /** Set or remove a handler for a trapa code.
     
-    \param  trap            The value passed to the trapa opcode.
+    \param  code            The value passed to the trapa opcode.
     \param  hnd             A pointer to the procedure to handle the trap.
     \param  data            A pointer that will be passed along to the callback.
 
     \retval 0               On success.
 
     \sa trapa_get_handler()
 */
-int trapa_set_handler(trapa_t trap, trapa_handler hnd, void *data);
+int trapa_set_handler(trapa_t code, trapa_handler hnd, void *data);
 
 /** Get an existing TRAPA handler.
 
@@ -87,7 +87,7 @@ int trapa_set_handler(trapa_t trap, trapa_handler hnd, void *data);
 
     \sa trapa_set_handler()
 */
-trapa_handler trapa_get_handler(trapa_t trap, void **data);
+trapa_handler trapa_get_handler(trapa_t code, void **data);
 
 /** @} */
 

kernel/arch/dreamcast/include/dc/maple/keyboard.h

@@ -247,7 +247,7 @@ typedef enum __packed kbd_key {
     KBD_KEY_QUOTE        = 0x34, /**< \brief " key */
     KBD_KEY_TILDE        = 0x35, /**< \brief ~ key */
     KBD_KEY_COMMA        = 0x36, /**< \brief , key */
-    KBD_KEY_PERIOD       = 0x37, /**< \brief . key */
+    KBD_KEY_PERIOD       = 0x37, /**< \brief \. key */
     KBD_KEY_SLASH        = 0x38, /**< \brief Slash key */
     KBD_KEY_CAPSLOCK     = 0x39, /**< \brief Caps Lock key */
     KBD_KEY_F1           = 0x3a, /**< \brief F1 key */

kernel/arch/dreamcast/include/dc/perf_monitor.h

@@ -115,5 +115,8 @@ void perf_monitor_exit(void);
 */
 void perf_monitor_print(FILE *f);
 
+/** @} */
+
 __END_DECLS
+
 #endif /* __KOS_PERF_MONITOR_H */

kernel/arch/dreamcast/include/dc/pvr/pvr_header.h

@@ -351,5 +351,8 @@ typedef __attribute__((aligned(32))) struct pvr_poly_hdr {
 
 _Static_assert(sizeof(pvr_poly_hdr_t) == 32, "Invalid header size");
 
+/** @} */
+
 __END_DECLS
+
 #endif /* __DC_PVR_PVR_HEADER_H */

kernel/arch/dreamcast/include/dc/sound/sound.h

@@ -222,7 +222,7 @@ void snd_adpcm_split(uint32_t *data, uint32_t *left, uint32_t *right, size_t siz
     This function returns actual the channel position
     that stores in SPU memory and updated by the SPU firmware.
 
-    \param  chn             The channel to retrieve position.
+    \param  ch              The channel to retrieve position.
 
     \return                 Last channel position in samples.
 */
@@ -233,7 +233,7 @@ uint16_t snd_get_pos(unsigned int ch);
     This function returns actual the channel playback state
     that stores in AICA registers directly.
 
-    \param  chn             The channel to check.
+    \param  ch              The channel to check.
 
     \return                 True if the channel is playing.
 */

kernel/arch/dreamcast/include/dc/sound/stream.h

@@ -194,7 +194,6 @@ void snd_stream_filter_remove(snd_stream_hnd_t hnd,
     This function has no effect. The stream is prefilled on start.
     This is deprecated and should be removed if used.
 
-    \param  hnd             Param.
 */
 static const int __snd_stream_prefill   __depr("snd_stream_prefill has no effect and should be removed") = 0;
 #define snd_stream_prefill(x)  ((void)__snd_stream_prefill)