Some edit on documentation

c128lib · May 21, 2024 · d4b2114 · d4b2114
1 parent efcae0d
commit d4b2114
Show file tree

Hide file tree

Showing 5 changed files with 160 additions and 63 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,11 +1,106 @@
 # Welcome to contributing guide
 TBD
+
 ## Guide to contributing code
-TBD
+
+### Declaration case type
+Labels must use the **Snake Case with all capital letters**.
+<pre>
+.label PAGE0_PAGE_POINTER   = $D507
+</pre>
+
+Macro must use the **Pascal Case**.
+<pre>
+.macro BasicUpstart128() { }
+</pre>
+
+Functions must use the **Camel Case**.
+<pre>
+.function incArgument() { }
+</pre>
+
+### Argument check
+If a macro or function has arguments that can only take on certain values, it is advisable to insert checks to ensure correct use.
+You can use the .errorif keyword to raise an error.
+
+``` Assembly
+.macro FillMemory(address, length, value) {
+  .errorif (length < 5 || length > 255), "length must be from 5 to 255"
+...
+}
+```
+
+It is also a good idea to add assertions at the end of the macro body to check that the error is raised correctly.
+
+``` Assembly
+.asserterror "FillMemory($A000, 4, 10)", { FillMemory($A000, 4, 10) }
+.asserterror "FillMemory($A000, 256, 10)", { FillMemory($A000, 256, 10) }
+```
+
+### Static test
+Static testing should be performed to verify that the correct code is produced. At the end of each macro, add one or more assertions to compare the code generated by the macro with the expected code.
+
+``` Assembly
+.macro SetCommonRAM(config) {
+    lda #config
+    sta Mmu.RAM_CONFIG
+}
+.assert "SetCommonRAM(COMMON_RAM_16K | COMMON_RAM_BOTH) sets accumulator to 0f", { SetCommonRAM(Mmu.COMMON_RAM_16K | Mmu.COMMON_RAM_BOTH) }, {
+  lda #%00001111; sta $d506
+}
+```
+
+Static testing is very important especially where the code can vary depending on the arguments with which a macro is called.
+
+### Hex values
+
+Hex values should be written with two or four characters as needed. The letters should be capitalized.
+
+``` Assembly
+.label CONFIGURATION        = $D500
+```
 
 ## Guide to contributing documentation
 ### File header
-TBD
+Every file should have an header like this:
+
+<pre>
+/**
+ * @file math.asm
+ * @brief Math module
+ * @details Simple macros for math operations.
+ *
+ * @author Raffaele Intorcia <a href="https://github.com/intoinside">@intoinside</a> raffaele.intorcia@gmail.com
+ *
+ * @copyright MIT License
+ * Copyright (c) 2024 c128lib - https://github.com/c128lib
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ * @date 2024
+ */
+</pre>
+
+* a @brief keyword with a short description (typically one or two line)
+* a @details keyword (optional) with a longer description, with some hint about code used and comparison with similar code
+* one or more @author keyword with name, Github profile link and email
+* a @date keyword indicating year of creating file
 
 ### Subroutine and macro header
 Every subroutine and macro should have an header like this:
@@ -38,4 +133,4 @@ or output value
 
 #### Other keywords under evaluation
 * a @example keyword (optional) for pointing to other source code where method is used
-* a @note keyword (optional) for a simple usage code
+* a @note keyword (optional) for a simple usage code
diff --git a/lib/kernal.asm b/lib/kernal.asm
@@ -70,7 +70,6 @@
 .label UNLSN = $E526
 /** Sets serial device for fast serial input https://c128lib.github.io/Reference/E000#E5C3 */
 .label SPIN = $E5C3
-
 /** Sets serial device for fast serial output https://c128lib.github.io/Reference/E000#E5D6 */
 .label SPOUT = $E5D6
 /** Sets serial device for fast serial input or output https://c128lib.github.io/Reference/E000#E5FB */
@@ -149,7 +148,6 @@
 .label NMI = $FA40
 /** Handles IRQ interrupts https://c128lib.github.io/Reference/E000#FA65 */
 .label IRQ = $FA65
-
 /** Serial fast input or output https://c128lib.github.io/Reference/E000#FF47 */
 .label JSPIN_SPOUT = $FF47
 /** Close all files to a device https://c128lib.github.io/Reference/E000#FF4A */

diff --git a/lib/mmu.asm b/lib/mmu.asm
@@ -64,44 +64,44 @@
 .label PAGE1_BLOCK_POINTER  = $D50A
 /** Version register https://c128lib.github.io/Reference/D500#D50B */
 .label MMU_VERSION          = $D50B
-/** Configuration register https://c128lib.github.io/Reference/FF00#FF00 */
+/** Configuration register https://c128lib.github.io/Reference/E000#FF00 */
 .label LOAD_CONFIGURATION   = $FF00
-/** Load configuration register A https://c128lib.github.io/Reference/FF00#FF01 */
+/** Load configuration register A https://c128lib.github.io/Reference/E000#FF01 */
 .label LOAD_PRECONFIG_A     = $FF01
-/** Load configuration register B https://c128lib.github.io/Reference/FF00#FF02 */
+/** Load configuration register B https://c128lib.github.io/Reference/E000#FF02 */
 .label LOAD_PRECONFIG_B     = $FF02
-/** Load configuration register C https://c128lib.github.io/Reference/FF00#FF03 */
+/** Load configuration register C https://c128lib.github.io/Reference/E000#FF03 */
 .label LOAD_PRECONFIG_C     = $FF03
-/** Load configuration register D https://c128lib.github.io/Reference/FF00#FF04 */
+/** Load configuration register D https://c128lib.github.io/Reference/E000#FF04 */
 .label LOAD_PRECONFIG_D     = $FF04
 
-/** Mask for configuration bit 0 to set ROM active on address $d000-$dfff */
+/** Mask for configuration bit 0 to set ROM active on address $D000-$DFFF */
 .label IO_ROM             = %00000000
-/** Mask for configuration bit 0 to set RAM active on address $d000-$dfff */
+/** Mask for configuration bit 0 to set RAM active on address $D000-$DFFF */
 .label IO_RAM             = %00000001
 
-/** Mask for configuration bit 1 to set ROM active on address $4000-$7fff (Basic low rom) */
+/** Mask for configuration bit 1 to set ROM active on address $4000-$7FFF (Basic low rom) */
 .label ROM_LOW_ROM        = %00000000
-/** Mask for configuration bit 1 to set RAM active on address $4000-$7fff (Basic low rom) */
+/** Mask for configuration bit 1 to set RAM active on address $4000-$7FFF (Basic low rom) */
 .label ROM_LOW_RAM        = %00000010
 
 /** Mask for configuration bits 2-3 to set ROM active on upper portion of BASIC ROM ($8000-$AFFF), plus monitor ROM ($B000-$BFFF) */
 .label ROM_MID_ROM        = %00000000
 /** Mask for configuration bits 2-3 to set internal function ROM: refers to ROM in the free ROM socket on the 128 circuit board */
 .label ROM_MID_INT        = %00000100
-/** Mask for configuration bits 2-3 to set xxternal function ROM: refers to ROM in a cartridge plugged into the expansion port. */
+/** Mask for configuration bits 2-3 to set external function ROM: refers to ROM in a cartridge plugged into the expansion port. */
 .label ROM_MID_EXT        = %00001000
 /** Mask for configuration bits 2-3 to set RAM active on upper portion of BASIC ROM ($8000-$AFFF), plus monitor ROM ($B000-$BFFF) */
 .label ROM_MID_RAM        = %00001100
 
-// bit 4-5 - controls rom mid space $c000-$ffff (Screen editor rom, kernal rom)
-/** Mask for configuration bits 4-5 to set ROM active on screen editor ROM ($c000-$cfff), character ROM ($d000-$Ddfff), Kemal ROM ($e000-$ffff) */
+// bit 4-5 - controls rom mid space $C000-$FFFF (Screen editor rom, kernal rom)
+/** Mask for configuration bits 4-5 to set ROM active on screen editor ROM ($C000-$CFFF), character ROM ($D000-$DFFF), Kemal ROM ($E000-$FFFF) */
 .label ROM_HI             = %00000000
 /** Mask for configuration bits 4-5 to set internal function ROM: refers to ROM in the free ROM socket on the 128 circuit board. */
 .label ROM_HI_INT         = %00010000
 /** Mask for configuration bits 4-5 to set external function ROM: refers to ROM in a cartridge plugged into the expansion port. */
 .label ROM_HI_EXT         = %00100000
-/** Mask for configuration bits 4-5 to set RAM active on screen editor ROM ($c000-$cfff), character ROM ($d000-$Ddfff), Kemal ROM ($e000-$ffff) */
+/** Mask for configuration bits 4-5 to set RAM active on screen editor ROM ($C000-$CFFF), character ROM ($D000-$DFFF), Kemal ROM ($E000-$FFFF) */
 .label ROM_HI_RAM         = %00110000
 
 /** Mask for configuration bit 6 to set block 0 active */

diff --git a/lib/vdc.asm b/lib/vdc.asm
@@ -75,16 +75,16 @@
 /** White color code */
 .label VDC_WHITE = 15
 
-.label COLOR80    = $ce5c
+.label COLOR80    = $CE5C
 
-.label MODE       = $d7
+.label MODE       = $D7
 
 .label TEXT_SCREEN_80_COL_WIDTH = 80
 
-/** Vdc address/status register */
-.label VDCADR     = $d600
-/** Vdc data register */
-.label VDCDAT     = $d601
+/** Vdc address/status register https://c128lib.github.io/Reference/D600#D600 */
+.label VDCADR     = $D600
+/** Vdc data register https://c128lib.github.io/Reference/D600#D601 */
+.label VDCDAT     = $D601
 
 /** Total number of horizontal character positions https://c128lib.github.io/Reference/Vdc#00 */
 .label TOTALE_NUMBER_OF_HORIZONTAL_CHARACTER_POSITIONS    = $00

diff --git a/lib/vic2.asm b/lib/vic2.asm
@@ -160,7 +160,7 @@
 .label SPRITE_MOTION_6      = $11C0
 /** Sprite 7 movement control data https://c128lib.github.io/Reference/1100#117E */
 .label SPRITE_MOTION_7      = $11CB
-/** Offset between sprite control data pointers https://c128lib.github.io/Reference/1100#117E */
+/** Offset between sprite control data pointers */
 .label SPRITE_MOTION_OFFSET = $0B
 
 .label SPRITE_MAIN_DIR_UP   = $00
@@ -180,49 +180,49 @@
 .label SPRITE_MASK_6 = %01000000
 .label SPRITE_MASK_7 = %10000000
 
-/** Vic2 first shadow register  https://c128lib.github.io/Reference/11D6 */
+/** Vic2 first shadow register  https://c128lib.github.io/Reference/1100#11D6 */
 .label SHADOW_VIC2          = $11D6
-/** Sprite 0 shadow register x-coordinate https://c128lib.github.io/Reference/11D6#11D6 */
+/** Sprite 0 shadow register x-coordinate https://c128lib.github.io/Reference/1100#11D6 */
 .label SHADOW_SPRITE_0_X    = SHADOW_VIC2 + $00
-/** Sprite 0 shadow register y-coordinate https://c128lib.github.io/Reference/11D6#11D7 */
+/** Sprite 0 shadow register y-coordinate https://c128lib.github.io/Reference/1100#11D7 */
 .label SHADOW_SPRITE_0_Y    = SHADOW_VIC2 + $01
-/** Sprite 1 shadow register x-coordinate https://c128lib.github.io/Reference/11D6#11D8 */
+/** Sprite 1 shadow register x-coordinate https://c128lib.github.io/Reference/1100#11D8 */
 .label SHADOW_SPRITE_1_X    = SHADOW_VIC2 + $02
-/** Sprite 1 shadow register y-coordinate https://c128lib.github.io/Reference/11D6#11D9 */
+/** Sprite 1 shadow register y-coordinate https://c128lib.github.io/Reference/1100#11D9 */
 .label SHADOW_SPRITE_1_Y    = SHADOW_VIC2 + $03
-/** Sprite 2 shadow register x-coordinate https://c128lib.github.io/Reference/11D6#11DA */
+/** Sprite 2 shadow register x-coordinate https://c128lib.github.io/Reference/1100#11DA */
 .label SHADOW_SPRITE_2_X    = SHADOW_VIC2 + $04
-/** Sprite 2 shadow register y-coordinate https://c128lib.github.io/Reference/11D6#11DB */
+/** Sprite 2 shadow register y-coordinate https://c128lib.github.io/Reference/1100#11DB */
 .label SHADOW_SPRITE_2_Y    = SHADOW_VIC2 + $05
-/** Sprite 3 shadow register x-coordinate https://c128lib.github.io/Reference/11D6#11DC */
+/** Sprite 3 shadow register x-coordinate https://c128lib.github.io/Reference/1100#11DC */
 .label SHADOW_SPRITE_3_X    = SHADOW_VIC2 + $06
-/** Sprite 3 shadow register y-coordinate https://c128lib.github.io/Reference/11D6#11DD */
+/** Sprite 3 shadow register y-coordinate https://c128lib.github.io/Reference/1100#11DD */
 .label SHADOW_SPRITE_3_Y    = SHADOW_VIC2 + $07
-/** Sprite 4 shadow register x-coordinate https://c128lib.github.io/Reference/11D6#11DE */
+/** Sprite 4 shadow register x-coordinate https://c128lib.github.io/Reference/1100#11DE */
 .label SHADOW_SPRITE_4_X    = SHADOW_VIC2 + $08
-/** Sprite 4 shadow register y-coordinate https://c128lib.github.io/Reference/11D6#11DF */
+/** Sprite 4 shadow register y-coordinate https://c128lib.github.io/Reference/1100#11DF */
 .label SHADOW_SPRITE_4_Y    = SHADOW_VIC2 + $09
-/** Sprite 5 shadow register x-coordinate https://c128lib.github.io/Reference/11D6#11E0 */
+/** Sprite 5 shadow register x-coordinate https://c128lib.github.io/Reference/1100#11E0 */
 .label SHADOW_SPRITE_5_X    = SHADOW_VIC2 + $0A
-/** Sprite 5 shadow register y-coordinate https://c128lib.github.io/Reference/11D6#11E1 */
+/** Sprite 5 shadow register y-coordinate https://c128lib.github.io/Reference/1100#11E1 */
 .label SHADOW_SPRITE_5_Y    = SHADOW_VIC2 + $0B
-/** Sprite 6 shadow register x-coordinate https://c128lib.github.io/Reference/11D6#11E2 */
+/** Sprite 6 shadow register x-coordinate https://c128lib.github.io/Reference/1100#11E2 */
 .label SHADOW_SPRITE_6_X    = SHADOW_VIC2 + $0C
-/** Sprite 6 shadow register y-coordinate https://c128lib.github.io/Reference/11D6#11E3 */
+/** Sprite 6 shadow register y-coordinate https://c128lib.github.io/Reference/1100#11E3 */
 .label SHADOW_SPRITE_6_Y    = SHADOW_VIC2 + $0D
-/** Sprite 7 shadow register x-coordinate https://c128lib.github.io/Reference/11D6#11E4 */
+/** Sprite 7 shadow register x-coordinate https://c128lib.github.io/Reference/1100#11E4 */
 .label SHADOW_SPRITE_7_X    = SHADOW_VIC2 + $0E
-/** Sprite 7 shadow register y-coordinate https://c128lib.github.io/Reference/11D6#11E5 */
+/** Sprite 7 shadow register y-coordinate https://c128lib.github.io/Reference/1100#11E5 */
 .label SHADOW_SPRITE_7_Y    = SHADOW_VIC2 + $0F
-/** Sprite shadow register msb for setting x pos over 255 px https://c128lib.github.io/Reference/11D6#11E6 */
+/** Sprite shadow register msb for setting x pos over 255 px https://c128lib.github.io/Reference/1100#11E6 */
 .label SHADOW_SPRITE_MSB_X  = SHADOW_VIC2 + $10
-/** Sprite-to-sprite collision shadow register https://c128lib.github.io/Reference/11D6#11E7 */
+/** Sprite-to-sprite collision shadow register https://c128lib.github.io/Reference/1100#11E7 */
 .label SHADOW_SPRITE_2S_COLLISION = SHADOW_VIC2 + $11
-/** Sprite-to-background collision shadow register https://c128lib.github.io/Reference/11D6#11E8 */
+/** Sprite-to-background collision shadow register https://c128lib.github.io/Reference/1100#11E8 */
 .label SHADOW_SPRITE_2B_COLLISION = SHADOW_VIC2 + $12
-/** Light pen horizontal position shadow register https://c128lib.github.io/Reference/11D6#11E9 */
+/** Light pen horizontal position shadow register https://c128lib.github.io/Reference/1100#11E9 */
 .label SHADOW_LIGHTPEN_X    = SHADOW_VIC2 + $13
-/** Light pen vertical position shadow register https://c128lib.github.io/Reference/11D6#11EA */
+/** Light pen vertical position shadow register https://c128lib.github.io/Reference/1100#11EA */
 .label SHADOW_LIGHTPEN_Y    = SHADOW_VIC2 + $14
 
 .label COLOR_RAM            = $D800
@@ -231,49 +231,53 @@
 .label RASTER_MAX_PAL       = 312
 .label RASTER_MAX_NTSC      = 263
 
-/** Extra bit for raster register */
+/** Extra bit for raster register https://c128lib.github.io/Reference/D000#D011 */
 .label CONTROL_1_RASTER8  = %10000000
-/** Extended background color mode */
+/** Extended background color mode https://c128lib.github.io/Reference/D000#D011 */
 .label CONTROL_1_ECM      = %01000000
-/** Char mode or bitmapped mode */
+/** Char mode or bitmapped mode https://c128lib.github.io/Reference/D000#D011 */
 .label CONTROL_1_BMM      = %00100000
-/** Enable or disable Vic screen */
+/** Enable or disable Vic screen https://c128lib.github.io/Reference/D000#D011 */
 .label CONTROL_1_DEN      = %00010000
-/** Vertical screen row count */
+/** Vertical screen row count https://c128lib.github.io/Reference/D000#D011 */
 .label CONTROL_1_RSEL     = %00001000
 
 /** Reset bit */
 .label CONTROL_2_RES      = %00100000
-/** Multicolor mode */
+/** Multicolor mode https://c128lib.github.io/Reference/D000#D016 */
 .label CONTROL_2_MCM      = %00010000
 /** Horizontal screen column count */
 .label CONTROL_2_CSEL     = %00001000
 
-/** Irq status */
+/** Irq status https://c128lib.github.io/Reference/D000#D019 */
 .label IRR_IRQ            = %10000000
-/** Light pen signal */
+/** Light pen signal https://c128lib.github.io/Reference/D000#D019 */
 .label IRR_LIGHTPEN       = %00001000
-/** Sprite to sprite collision */
+/** Sprite to sprite collision https://c128lib.github.io/Reference/D000#D019 */
 .label IRR_SPR_SPR        = %00000100
-/** Sprite to background collision */
+/** Sprite to background collision https://c128lib.github.io/Reference/D000#D019 */
 .label IRR_SPR_BG         = %00000010
-/** Irq on raster line */
+/** Irq on raster line https://c128lib.github.io/Reference/D000#D019 */
 .label IRR_RASTER         = %00000001
 
-/** Light pen interrupt */
+/** Light pen interrupt https://c128lib.github.io/Reference/D000#D01A */
 .label IMR_LIGHTPEN       = %00001000
-/** Sprite to sprite collision interrupt */
+/** Sprite to sprite collision interrupt https://c128lib.github.io/Reference/D000#D01A */
 .label IMR_SPR_SPR        = %00000100
-/** Sprite to background collision interrupt */
+/** Sprite to background collision interrupt https://c128lib.github.io/Reference/D000#D01A */
 .label IMR_SPR_BG         = %00000010
-/** Raster interrupt */
+/** Raster interrupt https://c128lib.github.io/Reference/D000#D01A */
 .label IMR_RASTER         = %00000001
 
-// Graphic modes
+/** Standard text mode https://c128lib.github.io/Reference/Vic#character-display-modes */
 .label STANDARD_TEXT_MODE     = %000
+/** Multicolor text mode https://c128lib.github.io/Reference/Vic#multicolor-character-mode */
 .label MULTICOLOR_TEXT_MODE   = %001
+/**+ Bitmapped display mode https://c128lib.github.io/Reference/Vic#bitmapped-display-modes */
 .label STANDARD_BITMAP_MODE   = %010
+/** Multicolor bitmapped mode https://c128lib.github.io/Reference/Vic#multicolor-bitmapped-mode */
 .label MULTICOLOR_BITMAP_MODE = %011
+/** Extended background color mode https://c128lib.github.io/Reference/Vic#extended-background-color-mode */
 .label EXTENDED_TEXT_MODE     = %100
 
 .label MODE_ECM               = %100