doc improvements

.doxygen_config

@@ -290,11 +290,11 @@ TAB_SIZE               = 4
 # @} or use a double escape (\\{ and \\})
 
 ALIASES                = "modifies=\par Modifies Registers^^" \
-                         "type=\xrefitem type \"Code Type\" \"Code Type\"" \
                          "macro=\qualifier macro \brief" \
                          "function=\qualifier subroutine \brief" \
                          "module=\file ^^ \brief" \
                          "clock_dependent=\xrefitem clock_dependant \"Clock Speed Dependence\" \"Clock speed dependent code\"" 
+                         # "type=\xrefitem type \"Code Type\" \"Code Type\"" \
 
 # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources
 # only. Doxygen will then generate output that is more tailored for C. For

.extra_docs.s65

@@ -60,7 +60,7 @@
 ;;********************************************************************************
 
 ;;********************************************************************************
-;; @defgroup utility
+;; @defgroup libs Libraries
 ;; @brief Code that does something useful and is intended to be used in other code
 ;;
 ;;********************************************************************************

doxy-asm65.py

@@ -18,7 +18,7 @@ from typing import Callable
 #    Parameters documented with the @param command are put into the paranthesis (function arguments) with `Param` as type (@ref handle_procedure)
 #  - turns macros `.macro` into function statements with `macro` as return type with the parameter macros
 #    as function arguments with `Param` type (@ref handle_procedure)
-#  - enums become ... enums, documentation of enum members after their name is also handled (@ref handle_procedure)
+#  - enums become ... enums, documentation of enum members after their name is also handled when using ;;< (@ref handle_procedure)
 #  - labeled storage allocations with `.byte`, `.res`, `.ascii` etc. are turned into variable declarations with the label as variable name (@ref handle_procedure)
 #    - if allocations are strings, they are concatenated together to `char * LABEL_NAME = "<string(s)>";`
 #    - if there are multiple non-string allocations: `bytes LABEL_NAME[] = {alloc1, alloc2, ...};`
@@ -87,7 +87,7 @@ def parse_custom_language(file_content: str):
             s += p_args
             s += ");\n"
         elif p_type == "enum":
-            p_code = re.sub(r"( *(?:;;.*)?\n)", r",\1", p_code)
+            p_code = re.sub(r"(.*=.*?)( *(?:;;.*)?\n)", r"\1,\2", p_code)
             s += f"enum {p_name}" + "{\n" + p_code + "};"
         else:
             raise NotImplementedError(f"handle_procedure not implemented for procedure type {p_type}")

programs/dht.s65

@@ -1,8 +1,10 @@
 ;;********************************************************************************
-;; @module SPI
+;; @file
-;; @type driver
+;; @brief DHT22 driver (WIP)
+;; @ingroup driver
 ;; @details
 ;; @depends IO-W65C22N
+;; 
 ;;********************************************************************************
 
 ;;TODO EVERYTHING

programs/ps2_keyboard_simple_handler.h65

@@ -1,6 +1,7 @@
 ;;********************************************************************************
-;; @module ps2_keyboard_simple_handler
+;; @file
-;; @type system
+;; @brief Simple PS/2 keyboard handler
+;; @ingroup libs
 ;; @details:
 ;;	This module processes keyboard scancodes from the ps2_keyboard driver.
 ;;  It requires a PS/2 keyboard that supports scancode set 3.

programs/ps2_keyboard_text_handler.h65

@@ -1,7 +1,8 @@
 ; normal
 ;;********************************************************************************
-;; @module ps2_keyboard_text_handler
+;; @file
-;; @type system
+;; @brief PS/2 Keyboard handler for text input
+;; @ingroup libs
 ;; @details
 ;;	This module processes keyboard scancodes from the ps2_keyboard driver.
 ;;  It requires a PS/2 keyboard that supports scancode set 3.

programs/ps2_keyboard_util.s65

@@ -31,7 +31,7 @@
 ;; - `B`: reprint menu
 ;; - `*`: jump home
 ;; For more details, see https://wiki.osdev.org/PS/2_Keyboard
-;; @ingroup applications keyboard
+;; @ingroup applications
 ;;********************************************************************************
 .proc ps2_keyboard_util
     stz kp::_DEBUG_VAL

programs/viu.s65

@@ -1,5 +1,6 @@
 ;;********************************************************************************
-;; @module VIU - VI Unimproved
+;; @file
+;; @brief VIU - VI Unimproved
 ;;********************************************************************************
 .include "lcd.h65"
 .include "ps2_keyboard_text_handler.h65"

system/buffer.h65

@@ -1,5 +1,6 @@
 ;;********************************************************************************
-;; @module ringbuffer
+;; @file
+;; @brief Ringbuffer
 ;; @details
 ;;   Size of the ringbuffer is RBUF_MEM_END - RBUF_MEM_START - 2, since two bytes
 ;;   are used by the read and write pointer
@@ -13,7 +14,7 @@
 ;;   RBUF_MEM_START: First address of ringbuffer memory space
 ;;   RBUF_MEM_END: Last address of ringbuffer memory space
 ;;   RBUF_NAME: Name of the ringbuffer
-;; @ingroup utility
+;; @ingroup libs
 ;;********************************************************************************
 .code
 

system/io_W65C22.h65

@@ -1,8 +1,9 @@
 ;;********************************************************************************
-;; @module IO-W65C22
+;; @file
+;; @brief VIA W65C22 header
 ;; @ingroup system
-;; @device Western Design - W65C22N Versatile Interface Adapter
 ;; @details
+;; @device Western Design - W65C22N Versatile Interface Adapter
 ;;********************************************************************************
 
 .ifndef INCLUDE_IOW65C22
@@ -10,7 +11,7 @@ INCLUDE_IOW65C22 = 1
 
 ;;********************************************************************************
 ;; @brief Versatile Interface Adapter (VIA) W65C22
-;; @ingroup utility
+;; @ingroup system
 ;; @device Western Design - W65C22N Versatile Interface Adapter
 ;; @todo rename to VIA
 ;; @warning @anchor via_hardware_bug
@@ -29,22 +30,22 @@ INCLUDE_IOW65C22 = 1
 ;;  Use like this: `VIA_ADDRESS + IO::RB`
 ;;********************************************************************************
 .enum
-    RB   = $0  ;; Register B (ORB/IRB)
+    RB   = $0  ;;< Register B (ORB/IRB)
-    RA   = $1  ;; Register A (ORA/IRA)
+    RA   = $1  ;;< Register A (ORA/IRA)
-    DDRB = $2  ;; Data Direction Register B
+    DDRB = $2  ;;< Data Direction Register B
-    DDRA = $3  ;; Data Direction Register A
+    DDRA = $3  ;;< Data Direction Register A
-    T1CL = $4  ;; Timer 1 Counter Low/High
+    T1CL = $4  ;;< Timer 1 Counter Low/High
     T1CH = $5
-    T1LL = $6  ;; Timer 1 Latch Low/High
+    T1LL = $6  ;;< Timer 1 Latch Low/High
     T1LH = $7
-    T2CL = $8  ;; Timer 2 Counter Low/High
+    T2CL = $8  ;;< Timer 2 Counter Low/High
     T2CH = $9
-    SR   = $a  ;; Shift Register
+    SR   = $a  ;;< Shift Register
-    ACR  = $b  ;; Auxiliary Control Register
+    ACR  = $b  ;;< Auxiliary Control Register
-    PCR  = $c  ;; Peripheral Control Register
+    PCR  = $c  ;;< Peripheral Control Register
-    IFR  = $d  ;; Interrupt Flag Register
+    IFR  = $d  ;;< Interrupt Flag Register
-    IER  = $e  ;; Interrupt Enable Register
+    IER  = $e  ;;< Interrupt Enable Register
-    RANH = $f  ;; RA without handshake
+    RANH = $f  ;;< RA without handshake
 .endenum
 
 .enum ACR_MASK  ; ACR Masks
@@ -62,25 +63,25 @@ INCLUDE_IOW65C22 = 1
 ;;********************************************************************************
 .enum ACR
     ; SR Modes
-    SR_DISABLE       = %00000000  ;; Disabled
+    SR_DISABLE       = %00000000  ;;< Disabled
-    SR_SIN_T2        = %00000100  ;; Shift in under control of T2
+    SR_SIN_T2        = %00000100  ;;< Shift in under control of T2
-    SR_SIN_PHI2      = %00001000  ;; Shift in under control of PHI2
+    SR_SIN_PHI2      = %00001000  ;;< Shift in under control of PHI2
-    SR_SIN_PHIE      = %00001100  ;; Shift in under control of external clock
+    SR_SIN_PHIE      = %00001100  ;;< Shift in under control of external clock
-    SR_SOUT_FREE_T2  = %00010000  ;; Shift out free running at T2 rate
+    SR_SOUT_FREE_T2  = %00010000  ;;< Shift out free running at T2 rate
-    SR_SOUT_T2       = %00010100  ;; Shift out under control of T2
+    SR_SOUT_T2       = %00010100  ;;< Shift out under control of T2
-    SR_SOUT_PHI2     = %00011000  ;; Shift out under control of PHI2
+    SR_SOUT_PHI2     = %00011000  ;;< Shift out under control of PHI2
-    SR_SOUT_PHIE     = %00011100  ;; Shift out under control of external clock
+    SR_SOUT_PHIE     = %00011100  ;;< Shift out under control of external clock
     ; T1 Modes
-    T1_IRQ_LOAD      = %00000000  ;; Timed interrupt each time T1 is loaded
+    T1_IRQ_LOAD      = %00000000  ;;< Timed interrupt each time T1 is loaded
-    T1_IRQ_CONT      = %01000000  ;; Continuous interrupts
+    T1_IRQ_CONT      = %01000000  ;;< Continuous interrupts
-    T1_IRQ_LOAD_PB7  = %10000000  ;; Timed interrupt each time T1 is loaded - PB7 One Shot output
+    T1_IRQ_LOAD_PB7  = %10000000  ;;< Timed interrupt each time T1 is loaded - PB7 One Shot output
-    T1_IRQ_CONT_PB7  = %11000000  ;; Continuous interrupts - PB7 Square wave output
+    T1_IRQ_CONT_PB7  = %11000000  ;;< Continuous interrupts - PB7 Square wave output
     ; T2 Modes
-    T2_IRQ_LOAD      = %00000000  ;; Timed interrupt each time T2 is loaded
+    T2_IRQ_LOAD      = %00000000  ;;< Timed interrupt each time T2 is loaded
-    T2_COUNT_PB6     = %00100000  ;; Count down with pulsen on PB6
+    T2_COUNT_PB6     = %00100000  ;;< Count down with pulsen on PB6
     ; Latch
-    LATCH_DISABLE    = %00000000  ;; `OR` this with IO::ACR_MASK::PA or IO::ACR_MASK::PB
+    LATCH_DISABLE    = %00000000  ;;< `OR` this with IO::ACR_MASK::PA or IO::ACR_MASK::PB
-    LATCH_ENBLE      = %00000011  ;; `OR` this with IO::ACR_MASK::PA or IO::ACR_MASK::PB
+    LATCH_ENBLE      = %00000011  ;;< `OR` this with IO::ACR_MASK::PA or IO::ACR_MASK::PB
 .endenum
 
 .enum PCR_MASK  ; PCR Masks
@@ -97,29 +98,29 @@ INCLUDE_IOW65C22 = 1
 ;;********************************************************************************
 .enum PCR
     ; CA1 Modes
-    CA1_IN_AE        = %00000000   ; Input-negative active edge
+    CA1_IN_AE        = %00000000    ;;< Input-negative active edge
-    CA1_IP_AE        = %00000001   ; Input-positive active edge
+    CA1_IP_AE        = %00000001    ;;< Input-positive active edge
     ; CA2 Modes
-    CA2_IN_AE        = %00000000  ; Input-negative active edge
+    CA2_IN_AE        = %00000000    ;;< Input-negative active edge
-    CA2_IN_AE_IRQ_IND= %00000010  ; Independent interrupt input-negative edge
+    CA2_IN_AE_IRQ_IND= %00000010    ;;< Independent interrupt input-negative edge
-    CA2_IP_AE        = %00000100  ; Input-positive active edge
+    CA2_IP_AE        = %00000100    ;;< Input-positive active edge
-    CA2_IP_AE_IRQ_IND= %00000110  ; Independent interrupt input-positive edge
+    CA2_IP_AE_IRQ_IND= %00000110    ;;< Independent interrupt input-positive edge
-    CA2_OUT_HANDSHAKE= %00001000  ; Handshake output
+    CA2_OUT_HANDSHAKE= %00001000    ;;< Handshake output
-    CA2_OUT_PULSE    = %00001010  ; Pulse output
+    CA2_OUT_PULSE    = %00001010    ;;< Pulse output
-    CA2_OUT_LOW      = %00001100  ; Low output
+    CA2_OUT_LOW      = %00001100    ;;< Low output
-    CA2_OUT_HIGH     = %00001110  ; High output
+    CA2_OUT_HIGH     = %00001110    ;;< High output
     ; CB1 Modes
-    CB1_IN_AE        = %00000000   ; Input-negative active edge
+    CB1_IN_AE        = %00000000    ;;< Input-negative active edge
-    CB1_IP_AE        = %00010000   ; Input-positive active edge
+    CB1_IP_AE        = %00010000    ;;< Input-positive active edge
     ; CB2 Modes
-    CB2_IN_AE        = %00000000  ; Input-negative active edge
+    CB2_IN_AE        = %00000000    ;;< Input-negative active edge
-    CB2_IN_AE_IRQ_IND= %00100000  ; Independent interrupt input-negative edge
+    CB2_IN_AE_IRQ_IND= %00100000    ;;< Independent interrupt input-negative edge
-    CB2_IP_AE        = %01000000  ; Input-positive active edge
+    CB2_IP_AE        = %01000000    ;;< Input-positive active edge
-    CB2_IP_AE_IRQ_IND= %01100000  ; Independent interrupt input-positive edge
+    CB2_IP_AE_IRQ_IND= %01100000    ;;< Independent interrupt input-positive edge
-    CB2_OUT_HANDSHAKE= %10000000  ; Handshake output
+    CB2_OUT_HANDSHAKE= %10000000    ;;< Handshake output
-    CB2_OUT_PULSE    = %10100000  ; Pulse output
+    CB2_OUT_PULSE    = %10100000    ;;< Pulse output
-    CB2_OUT_LOW      = %11000000  ; Low output
+    CB2_OUT_LOW      = %11000000    ;;< Low output
-    CB2_OUT_HIGH     = %11100000  ; High output
+    CB2_OUT_HIGH     = %11100000    ;;< High output
 .endenum
 
 

system/irq_handler.h65

@@ -1,5 +1,6 @@
 ;;********************************************************************************
-;; @module WIP irq handler with jump tables and stuff
+;; @file
+;; @brief WIP irq handler with jump tables and stuff
 ;; @ingroup system
 ;;********************************************************************************
 .ifndef INCLUDE_IRQ_HANDLER

system/keypad.h65

@@ -1,6 +1,6 @@
 ;;********************************************************************************
-;; @module keypad4x4
+;; @file
-;; @device 4x4 Matrix Keypad
+;; @brief 4x4 Matrix Keypad driver
 ;; @details
 ;;   The LCD must be connected to a W65C22N Interface Chip:
 ;;     - IO.RA0-7  -> 

system/lcd.h65

@@ -1,5 +1,6 @@
 ;;********************************************************************************
-;; @module LCD-W164B
+;; @file
+;; @brief LCD-W164B driver
 ;; @ingroup drivers
 ;; @device ELECTRONIC ASSEMBLY - W164B-NLW
 ;; @details

system/ps2_keyboard.h65

@@ -1,5 +1,6 @@
 ;;********************************************************************************
-;; @module ps2_keyboard 
+;; @file
+;; @brief PS/2 Keyboard driver 
 ;; @ingroup drivers
 ;; @details
 ;;  Support for a PS2 Keyboard using the shift register of a 6522 VIA
@@ -77,17 +78,17 @@ RESEND      = $fe   ;; unsuccessful transmission
 
 
 .enum STATUS
-    RECEIVE_KEYS	= %10000000     ;; keyboard sends scancodes
+    RECEIVE_KEYS	= %10000000     ;;< keyboard sends scancodes
-    RECEIVE_ANSWER	= %01000000     ;; keyboard replies to a command
+    RECEIVE_ANSWER	= %01000000     ;;< keyboard replies to a command
-    SEND_CMD   		= %00100000     ;; host sends/sent the command byte
+    SEND_CMD   		= %00100000     ;;< host sends/sent the command byte
-    SEND_DATA   	= %00010000     ;; host sends/sent the data byte
+    SEND_DATA   	= %00010000     ;;< host sends/sent the data byte
-    SEND_RECV   	= %00001000     ;; keyboard sends additional data byte
+    SEND_RECV   	= %00001000     ;;< keyboard sends additional data byte
-    SEND        	= SEND_CMD | SEND_DATA | SEND_RECV ;; host is sending something, only used for checking status
+    SEND        	= SEND_CMD | SEND_DATA | SEND_RECV ;;< host is sending something, only used for checking status
     NONE			= %00000000
 .endenum
 
 .enum TYPEMATIC
-    REPEAT_MASK     = %00011111     ;; 00000 = 30Hz, ..., 11111 = 2Hz
+    REPEAT_MASK     = %00011111     ;;< 00000 = 30Hz, ..., 11111 = 2Hz
     DELAY250        = %00000000
     DELAY500        = %00100000
     DELAY750        = %01000000

system/spi.h65

@@ -1,5 +1,6 @@
 ;;********************************************************************************
-;; @module SPI-P
+;; @file
+;; @brief SPI Perpiheral
 ;; @details
 ;;  Support being a peripheral SPI device.
 ;; @depends IO-W65C22N

system/system.h65

@@ -1,8 +1,9 @@
 ;;********************************************************************************
-;; @module system
+;; @file
+;; @brief System header
 ;; @ingroup system
 ;; @details
-;;   Variable definitions for the current hardware setup
+;;   Variables for the current hardware setup
 ;;********************************************************************************
 
 .ifndef INCLUDE_SYSTEM

util/bit_macros.h65

@@ -1,3 +1,9 @@
+;;********************************************************************************
+;; @file
+;; @brief Macros for bitwise operations
+;; @ingroup libs
+;;********************************************************************************
+
 ;;********************************************************************************
 ;; @macro Use the bbs instruction by providing the bit as a mask
 ;; @details

util/math.h65

@@ -1,14 +1,13 @@
 ;;********************************************************************************
-;; @module math
+;; @file
-;; @details
+;; @brief Math library
-;;   Math library
 ;;********************************************************************************
 .ifndef INCLUDE_MATH
 INCLUDE_MATH = 1
 
 ;;********************************************************************************
 ;; @brief Math library
-;; @ingroup utility
+;; @ingroup libs
 ;;********************************************************************************
 .scope math
 

util/parity.h65

@@ -1,6 +1,12 @@
 .ifndef INCLUDE_PARITY
 INCLUDE_PARITY = 1
 
+;;********************************************************************************
+;; @file
+;; @brief Macros for calculating parity
+;; @ingroup libs
+;;********************************************************************************
+
 .import count_set_bits
 
 ;;********************************************************************************

util/parity.s65

@@ -1,10 +1,9 @@
 .export count_set_bits
+
 ;;********************************************************************************
-;; @function Initialize the PS2 keyboard
+;; @function Count the number of set bits in the `A` register
-;; @details
-;;  Count the number of set bits in Y.
-;;  
 ;; @modifies A, X, Y
+;; @param A: Byte to count the set bits in
 ;; @returns Y: The number of set bits in the byte
 ;;********************************************************************************
 .proc count_set_bits

util/string.h65

@@ -1,7 +1,7 @@
 ;;********************************************************************************
-;; @module string
+;; @file
+;; @brief String utility library
 ;; @details
-;;   String utility
 ;; @see str
 ;;********************************************************************************
 .ifndef INCLUDE_STRING
@@ -12,7 +12,7 @@ INCLUDE_STRING = 1
 
 ;;********************************************************************************
 ;; @brief String utility
-;; @ingroup utility
+;; @ingroup libs
 ;;********************************************************************************
 .scope str
 Import str, strf, printf_buffer

utility.h65

@@ -1,11 +1,10 @@
 .ifndef INCLUDE_UTILITY
 INCLUDE_UTILITY = 1
 
-
 ;;********************************************************************************
 ;; @file
 ;; @brief Various useful macros
-;; @ingroup utility
+;; @ingroup libs
 ;;********************************************************************************
 
 .macpack longbranch     ; jeq, jge...