More on source code conventions.
Posted: Sun 13 Apr, 2008 9:45 am
I've been working on my own take on a asm source documentation generator and thought I'd solicit some input.
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:
The parser starts off by looking for pure comment lines. It is then kicked into action by an @doc: declaration. This helps prevent the parser from choking on code it wasn't meant to analyse.
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:
The "identifier" is a class name which is included for all the @doc:s. The purpose of this is it allows you to use CSS to specify a basic style for everything, and then override it with more specific styles for routines/data/files etc.
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:
As with "identifier", "descriptor" is a generic class name for styling purposes. The "name" is name of the descriptor, converted to lowercase. So the "INPUTS:" name becomes:
The only other thing is the format of the descriptors. Blocks of regular text will just be passed straight through after being wrapped in <p> </p> tags. Consecutive lines of text are concatenated into the same block. If there is an empty line separating two blocks of text, they receive their own <p> tag.
You can also define bulletted lists using asterisks:
The lists are actually generated as 2 column tables. If a list item starts with a single word followed by a hyphen, it will split down the hyphen and put the name in the left hand side and the value in the right hand side.
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:
Anything else is just spanned across both columns.
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.
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.