Doxygen for function documentation

Author: Stewmath

.gitignore

@@ -1,4 +1,5 @@
 build/
+doc/
 *.sav
 *.gbc
 *.sn*

Doxyfile

@@ -4,7 +4,10 @@
 # You may need to "make clean" after modifying this.
 USE_PRECOMPRESSED_ASSETS = true
 
+TOPDIR = $(CURDIR)
+
 OBJS = build/main.o
+DOCFILES = $(OBJS:.o=-s.c)
 
 TARGET = rom.gbc
 SYMFILE = $(TARGET:.gbc=.sym)
@@ -38,8 +41,11 @@ all: $(TARGET)
 
 $(TARGET): $(OBJS) linkfile
 	wlalink -s linkfile rom.gbc
-	@sed -i 's/^00//' $(SYMFILE)
 	rgbfix -Cjv -t "ZELDA NAYRUAZ8E" -k 01 -l 0x33 -m 0x1b -r 0x02 rom.gbc
+
+	# Fix the symbol file so that it's readable by bgb (not just no$gmb)
+	@sed -i 's/^00//' $(SYMFILE)
+
 ifeq ($(USE_PRECOMPRESSED_ASSETS),true)
 	@-md5sum -c ages.md5
 endif
@@ -141,6 +147,7 @@ build:
 	mkdir build/rooms
 	mkdir build/debug
 	mkdir build/tilesets
+	mkdir build/doc
 
 
 .PHONY: clean run force
@@ -150,7 +157,17 @@ force:
 	make
 
 clean:
-	rm -R build/ $(TARGET)
+	-rm -R build/ doc/ $(TARGET)
 
 run: all
 	$(GBEMU) $(TARGET) 2>/dev/null
+
+# --------------------------------------------------------------
+# Documentation generation
+# --------------------------------------------------------------
+
+doc: $(DOCFILES)
+	doxygen
+
+build/%-s.c: %.s | build
+	cd build/doc/; $(TOPDIR)/tools/asm4doxy.pl ../../$<

Makefile

@@ -6,6 +6,13 @@
   rgbfix is needed)
 * [Cygwin](http://cygwin.com/install.html) (Only required for windows users)
 
+## Tools needed to generate documentation
+
+Type "make doc" to generate documentation.
+
+* Perl
+* Doxygen
+
 # A note about compression
 
 A nice bit of progress I've made is the ability to de and re-compress all of the 

README.md

@@ -0,0 +1,11 @@
+/**
+ * \mainpage Oracle of Ages Disassembly
+ *
+ * \section Introduction
+ *
+ * Welcome to the Oracle of Ages disassembly. Hopefully this documentation will
+ * make the code at least vaguely navigatable.
+ *
+ * See the "Files" section for the bulk of the documentation.
+ *
+ */

doxygen_index.c

@@ -1,3 +1,6 @@
+;; The main file containing all the code in the game.
+;;
+
 .include "include/rominfo.s"
 .include "include/defines.s"
 .include "include/wram.s"
@@ -89,20 +92,36 @@
 
 .ORGA $0068
 
+;;
+; @addr{0068}
+; @param \a
+; @param \de
+;;
 addAToDe:
 	add e			; $0068
 	ld e,a			; $0069
 	ret nc			; $006a
 	inc d			; $006b
 	ret			; $006c
 
+;;
+; @addr{006d}
+; @param \a
+; @param \bc
+;;
 addAToBc:
 	add c			; $006d
 	ld c,a			; $006e
 	ret nc			; $006f
 	inc b			; $0070
 	ret			; $0071
 
+;;
+; Adds a*2 to de.
+; @addr{0072}
+; @param \a
+; @param \de
+;;
 addDoubleIndexToDe:
 	push hl			; $0072
 	add a			; $0073
@@ -116,6 +135,11 @@ addDoubleIndexToDe:
 	pop hl			; $007c
 	ret			; $007d
 
+;;
+; Adds a*2 to bc.
+; @addr{007e}
+; @param \a
+; @param \bc
 addDoubleIndexToBc:
 	push hl			; $007e
 	add a			; $007f
@@ -129,6 +153,12 @@ addDoubleIndexToBc:
 	pop hl			; $0088
 	ret			; $0089
 
+;;
+; Call a function in any bank, from any bank.
+; @addr{008a}
+; @param \e Bank of the function to call
+; @param \hl Address of the function to call
+;;
 interBankCall:
 	ld a,($ff97)		; $008a
 	push af			; $008d
@@ -183,6 +213,9 @@ bitTable:
 ; Rest of the header
 .DSB $7 0
 
+;;
+; The game's entrypoint.
+; @addr{0150}
 begin: ; 0150
 	nop
 	di
@@ -207,7 +240,11 @@ func_0169:
 	jp $4000
 
 
-; Returns in A the number of set bits in A
+;; Get the number of set bits in a.
+; @addr{0176}
+; @param a Passed as register to check, returns total number of set
+; bits.
+; @param[out] b Also set to the return value.
 getNumSetBits: ; 0176
 	ld b,$00		; $0176
 -
@@ -220,6 +257,13 @@ getNumSetBits: ; 0176
 	ld a,b			; $017f
 	ret			; $0180
 
+;;
+; Add a bcd-encoded number to a 16-bit memory address. If it would go above
+; $9999, the result is $9999.
+; @addr{0181}
+; @param[in] bc Number to add.
+; @param hl Address to add with and store result into.
+; @return @cflag Set if the value would have gone over $9999.
 addDecimalToHlRef:
 	ld a,(hl)		; $0181
 	add c			; $0182
@@ -235,6 +279,12 @@ addDecimalToHlRef:
 	ldd (hl),a		; $018d
 	ret			; $018e
 
+;; Subtract a bcd-encoded number from a 16-bit memory address. If it would go
+;; below 0, the result is 0.
+; @addr{018f}
+; @param[in] bc Value to subtract.
+; @param hl Address to subtract with and store result into.
+; @return @cflag Set if the value would have gone under $0000.
 subDecimalFromHlRef: ; 018f
 	ld a,(hl)		; $018f
 	sub c			; $0190
@@ -251,6 +301,12 @@ subDecimalFromHlRef: ; 018f
 	scf			; $019b
 	ret			; $019c
 
+;; Multiply A by C.
+; @addr{019d}
+; @param a Operand 1
+; @param[in] c Operand 2
+; @param[out] hl Result
+; \trashes{b,e}
 multiplyAByC: ; 019d
 	ld e,$08		; $019d
 	ld b,$00		; $019f
@@ -266,7 +322,10 @@ multiplyAByC: ; 019d
 	jr nz,-
 	ret			; $01ab
 
-; Multiplies A by $10 and stores result in bc.
+;; Multiply A by $10, store result in bc.
+; @addr{01ac}
+; @param a Value to multiply
+; @param[out] bc Result
 multiplyABy0x10: ; 01ac
 	swap a			; $01ac
 	ld b,a			; $01ae
@@ -277,7 +336,10 @@ multiplyABy0x10: ; 01ac
 	ld b,a			; $01b5
 	ret			; $01b6
 
-
+;; Multiply A by 8, store result in bc.
+; @addr{01b7}
+; @param a Value to multiply
+; @param[out] bc Result
 multiplyABy8: ; 01b7
 	swap a			; $01b7
 	rrca			; $01b9
@@ -289,6 +351,10 @@ multiplyABy8: ; 01b7
 	ld b,a			; $01c1
 	ret			; $01c2
 
+;; Multiply A by 4, store result in bc.
+; @addr{01c3}
+; @param a Value to multiply
+; @param[out] bc Result
 multiplyABy4: ; 01c3
 	ld b,$00		; $01c3
 	add a			; $01c5
@@ -298,7 +364,10 @@ multiplyABy4: ; 01c3
 	ld c,a			; $01cb
 	ret			; $01cc
 
-; Converts signed 8-bit value in A to signed 16-bit value in bc
+;; Convert a signed 8-bit value in A to signed 16-bit value in bc
+; @addr{01cd}
+; @param a Signed value
+; @param[out] bc Signed 16-bit value
 s8ToS16: ; 01cd
 	ld b,$ff		; $01cd
 	bit 7,a			; $01cf

main.s

@@ -994,7 +994,7 @@
 					.$func_descr
 					."\n */\n";
 				# Return type from doxygen comments.
-				if ( $func_descr =~ /[\@\\]return[^\s]*\s+([\w\:\/\(\)\[\]\%]+)/io )
+				if ( $func_descr =~ /[\@\\]return[^\s]*\s+([\w\:\/\(\)\[\]\%\\@]+)/io )
 				{
 					$func_return = $1;
 				}
@@ -1056,11 +1056,21 @@
 				elsif ( $func_proto eq "" )
 				{
 					$func_descr = $files_funcs_descr{$curr_file}{$func};
-					while ($func_descr =~ /[\@\\]param[^\s]*\s+([\w\:\/\(\)\[\]\%]+)/io)
+					while ($func_descr =~ /[\@\\]param([^\s]*)\s+([\w\:\/\(\)\[\]\%\\@]+)/io)
 					{
-						my $par = $1;
+						my $type = $1;
+						my $par = $2;
 						$par =~ s/\://go;
-						$func_proto .= "$par, ";
+						$par =~ s/^\\//go;
+						if ( $type eq "" )
+						{
+							$func_proto .= "$par, ";
+						}
+						else
+						{
+							$type =~ s/[\[\]]//go;
+							$func_proto .= "$type $par, ";
+						}
 						$func_descr =~ s/[\@\\]param//io;
 					}
 				}