Attempt for project to document itself, and moving to live version of nextreg.txt

data/nextreg.txt

@@ -1,11 +1,26 @@
+The ZX Next stores configuration state in a field of registers.
+These registers are accessible via two io ports or via the special nextreg instructions.
+
+Port 0x243B (9275) is used to select the register by number, listed below.
+Port 0x253B (9531) is used to read or write the register value.
+
+Some registers are accessible only during the initialization process.
+Registers 0x80 and above are inaccessible to the copper.
+
+Initial values are set during a hard or soft reset but may be modified by the operating system.
+A hard reset is generated at power on, by the F1 key or via a write to nextreg 0x02 with bit 1 set.
+A soft reset is generated by a hard reset, the F4 key or via a write to nextreg 0x02 with bit 0 set.
+
+NEXTREG REGISTER SPACE
+Generally a set bit indicates the property is asserted
 
 0x00 (00) => Machine ID
 (R)
   0000 1000 = EMULATORS
-  
+//
   0000 1010 = ZX Spectrum Next
   1111 1010 = ZX Spectrum Next Anti-brick
-  
+//
   1001 1010 = ZX Spectrum Next Core on UnAmiga Reloaded
   1010 1010 = ZX Spectrum Next Core on UnAmiga
   1011 1010 = ZX Spectrum Next Core on SiDi
@@ -192,7 +207,8 @@ have passed.
   ** CTS_n is only active if the seleced uart is in hw flow control mode.
 
 0x0E (14) => Core Version (sub minor number)
-(R) (see register 0x01 for the major and minor version number)
+(R)
+  (see register 0x01 for the major and minor version number)
 
 0x0F (15) => Board ID
 (R)
@@ -449,23 +465,28 @@ have passed.
 
 0x35 (53)  => Sprite Attribute 0
 0x75 (117) => Sprite Attribute 0 with automatic post increment of Sprite Number
-(W) See documentation at https://www.specnext.com/sprites/
+(W)
+  See documentation at https://www.specnext.com/sprites/
 
 0x36 (54)  => Sprite Attribute 1
 0x76 (118) => Sprite Attribute 1 with automatic post increment of Sprite Number
-(W) See documentation at https://www.specnext.com/sprites/
+(W)
+  See documentation at https://www.specnext.com/sprites/
 
 0x37 (55)  => Sprite Attribute 2
 0x77 (119) => Sprite Attribute 2 with automatic post increment of Sprite Number
-(W) See documentation at https://www.specnext.com/sprites/
+(W)
+  See documentation at https://www.specnext.com/sprites/
 
 0x38 (56)  => Sprite Attribute 3
 0x78 (120) => Sprite Attribute 3 with automatic post increment of Sprite Number
-(W) See documentation at https://www.specnext.com/sprites/
+(W)
+  See documentation at https://www.specnext.com/sprites/
 
 0x39 (57)  => Sprite Attribute 4
 0x79 (121) => Sprite Attribute 4 with automatic post increment of Sprite Number
-(W) See documentation at https://www.specnext.com/sprites/
+(W)
+  See documentation at https://www.specnext.com/sprites/
 
 0x40 (64) => Palette Index
 (R/W)
@@ -719,25 +740,30 @@ have passed.
    bit 0 = MSB of scroll amount
 
 0x75 (117) => Sprite Attribute 0 with automatic post increment of Sprite Number
-(W) see nextreg 0x35
+(W)
+  see nextreg 0x35
 
 0x76 (118) => Sprite Attribute 1 with automatic post increment of Sprite Number
-(W) see nextreg 0x36
+(W)
+  see nextreg 0x36
 
 0x77 (119) => Sprite Attribute 2 with automatic post increment of Sprite Number
-(W) see nextreg 0x37
+(W)
+  see nextreg 0x37
 
 0x78 (120) => Sprite Attribute 3 with automatic post increment of Sprite Number
-(W) see nextreg 0x38
+(W)
+  see nextreg 0x38
 
 0x79 (121) => Sprite Attribute 4 with automatic post increment of Sprite Number
-(W) see nextreg 0x39
+(W)
+  see nextreg 0x39
 
 0x7F (127) => User Register 0
 (R/W)
   bits 7:0 = Unused storage available to the user (soft reset = 0xff)
 
-NEXTREG 0x80 AND HIGHER ARE INACCESSIBLE TO THE COPPER
+// NEXTREG 0x80 AND HIGHER ARE INACCESSIBLE TO THE COPPER
 
 0x80 (128) => Expansion Bus Enable
 (R/W) (hard reset = 0)
@@ -1028,7 +1054,6 @@ Writes immediately change the current mmu mapping as if by port write
 
 0xC3 (195) => NMI Return Address MSB
 (R/W) (soft reset = 0)
-
   The return address written during an nmi acknowledge cycle is
   always stored in these registers.
 
@@ -1213,7 +1238,7 @@ progress is made in the main program.
 (R/W Issue 4 Only) (hard reset = 0)
   bit 7 = 1 to write to XADC DRP port, 0 to read from XADC DRP port **
   bits 6:0 = XADC DRP register address DADDR
-* An XADC register read or write is initiated by writing to this register
+  * An XADC register read or write is/ initiated by writing to this register
   * There must be at least six 28 MHz cycles after each r/w to this register
   ** Reads as 0
 
@@ -1225,8 +1250,6 @@ progress is made in the main program.
 0xFA (250) => XADC D1
 (R/W Issue 4 Only) (hard reset = 0)
   bits 7:0 = MSB data connected to XADC DRP data bus D15:8
-DRP reads store result here, DRP writes take value from here
-
---
+  * DRP reads store result here, DRP writes take value from here
 
 0xFF (255) => Reserved for internal use

src/app/registers/RegisterBrowser.tsx

@@ -9,6 +9,11 @@ interface RegisterBrowserProps {
   registers: Register[];
 }
 
+/**
+ * Renders the access details for a register, including its description, operations, and notes.
+ * @param access The register access data to render.
+ * @returns A React component that displays the register access details.
+ */
 export function renderAccess(access: RegisterAccess) {
   const renderTooltip = (notes: Note[]) => (
     <Tooltip id="tooltip">
@@ -56,6 +61,11 @@ export function renderAccess(access: RegisterAccess) {
   );
 }
 
+/**
+ * A component for browsing and searching through a list of registers.
+ * @param registers An array of Register objects to display.
+ * @returns A React component that allows users to browse and search registers.
+ */
 export default function RegisterBrowser({ registers }: RegisterBrowserProps) {
   const [searchTerm, setSearchTerm] = useState('');
 

src/app/registers/RegisterDetailClient.tsx

@@ -4,6 +4,12 @@ import { Container, Row, Col, Card, Tabs, Tab } from 'react-bootstrap';
 import { Register } from './types';
 import { renderAccess } from './RegisterBrowser';
 
+/**
+ * A client-side component that displays the details of a single register.
+ * @param register The register object to display.
+ * @param defaultActiveKey The default active tab to display.
+ * @returns A React component that displays the register details.
+ */
 export default function RegisterDetailClient({
   register,
   defaultActiveKey,

src/app/registers/page.tsx

@@ -3,6 +3,11 @@ import path from 'path';
 import RegisterBrowser from './RegisterBrowser';
 import { Register, RegisterAccess } from './types';
 
+/**
+ * Parses the content of the nextreg.txt file and returns an array of register objects.
+ * @param fileContent The content of the nextreg.txt file.
+ * @returns A promise that resolves to an array of Register objects.
+ */
 async function parseNextReg(fileContent: string): Promise<Register[]> {
   const registers: Register[] = [];
   const paragraphs = fileContent.split(/\n\s*\n/);