This is based on Timendus' asmdoc utility which he created for Vera, but with my own personal twist to make it more flexible and less prone to parsing errors.
I have created a test page using a work-in-progress generator at my googlepages site.
I think it will be easiest to explain this by example, so here is one of the comment blocks used to generate the file:
Code: Select all
;-------------------------------------------------------------------------------
;@doc:routine
;
; === alClip3DPolygon ===
;
; Clips a 3D polygon against the view frustum. Input is supplied in 16-bit 3D
; co-ordinates and output is 8-bit 2D projected co-ordinates.
;
; INPUTS:
; REGISTERS
; * A - Number of vertexes in the polygon.
; * BC - Address of vertex index list
; * HL - Address of clipping data
; * DE - Address of vertex list
; * IX - Output address
;
; OUTPUTS:
; REGISTERS
; * A - Number of vertexes in clipped polygon (0 if completely culled).
; * F - Zero flag set if polygon was culled.
;
; DESTROYED:
; REGISTERS
; * BC, DE, HL, IX
;
; MEMORY
; * g_alTempRAM - first 21 bytes destroyed
;
;@doc:end
;-------------------------------------------------------------------------------
The identifier following @doc: can be any name. In the test I used "routine" for code, "global" for global variables and "file" for file descriptions. The parser doesn't care (except for @doc:end, which is a reserved word) - it doesn't (yet) use this information, although it probably will later when I get around to index generation.
What it does do is include that name in the class specification in the HTML. ie:
Code: Select all
<div class="routine identifier">
Getting back to the point, the parser doesn't actually generate any code at this point. The @doc: just tells it what class to use for any following definitions.
The actual identifiers are declared Vera-style, using ===. Once it finds an identifier, it generates a header for it.
The next step is the descriptors. The descriptors are what actually supplies the information about the routine. When the parser encounters an === identifier ===, it creates a default descriptor called, oddly enough, "description". It inserts any text following the identifier into the description until it encounters another identifier, @doc:end or a custom descriptor.
Custom descriptors are declared by a single word on a new line followed by a colon (such as "INPUTS:" in the example). Each descriptor, including the default "description", receives it's own div as follows:
Code: Select all
<div class="name descriptor">
Code: Select all
<div class="inputs descriptor">
You can also define bulletted lists using asterisks:
Code: Select all
* item one
* item two
If the item starts with a hyphen, it assumes it is a continuation of a previous entry and put everything in the right hand side, such as this:
Code: Select all
BC - first line
- second line
If the line immediately before the first list item was not blank, it will be inserted as a caption to the list. (See "REGISTERS" in the example).
And that's about it! I'd like to hear your comments - especially how you think this would gel with your commenting style. I'd like this to be as reusable as possible.