More on source code conventions.

A General Discussion forum for TI calculators

Moderator: MaxCoderz Staff

Post Reply
User avatar
qarnos
Maxcoderz Staff
Posts: 227
Joined: Thu 01 Dec, 2005 9:04 am
Location: Melbourne, Australia

More on source code conventions.

Post by qarnos »

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:

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 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:

Code: Select all

<div class="routine identifier">
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:

Code: Select all

<div class="name descriptor">
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:

Code: Select all

<div class="inputs descriptor">
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:

Code: Select all

* item one
* item two
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:

Code: Select all

BC - first line
   - second line
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.
Last edited by qarnos on Fri 16 May, 2008 8:47 am, edited 1 time in total.
"I don't know why a refrigerator is now involved, but put that aside for now". - Jim e on unitedti.org

avatar courtesy of driesguldolf.
User avatar
Timendus
Calc King
Posts: 1729
Joined: Sun 23 Jan, 2005 12:37 am
Location: Netherlands
Contact:

Post by Timendus »

Looks like fun. How do you make it "less prone to parsing errors"? Maybe I could use some of it in Vera's tool :)

Two things I don't like about it:
- It parses to HTML (I kinda liked the idea of parsing to generic XML that can be used with anything - including a webbrowser with a bit of XSLT)
- I like the lay-out that I kinda ripped from Ben better :P But that's just a matter of stylesheet of course ;)
http://clap.timendus.com/ - The Calculator Link Alternative Protocol
http://api.timendus.com/ - Make your life easier, leave the coding to the API
http://vera.timendus.com/ - The calc lover's OS
User avatar
qarnos
Maxcoderz Staff
Posts: 227
Joined: Thu 01 Dec, 2005 9:04 am
Location: Melbourne, Australia

Post by qarnos »

Timendus wrote:Looks like fun. How do you make it "less prone to parsing errors"? Maybe I could use some of it in Vera's tool :)
Well, the main feature is the "@doc" think, which delimits the documentation so the parser doesn't try to parse stuff it shouldn't. I also use a list marker "*" rather that have the parser try to guess what is supposed to be a list. It also uses indentation as cues if it gets really confused.

I've added a pretty nifty z80 code parser - it can automagically detect blocks of code, wherever they are, and produce highlighted output with code aligned into columns for labels/opcode/operands/comments.

I am adding support for vera-style documentation, so you will be free to use it when it's working :) Hopefully I can release something functional this weekend.
Two things I don't like about it:
- It parses to HTML (I kinda liked the idea of parsing to generic XML that can be used with anything - including a webbrowser with a bit of XSLT)
I agree, but I don't know jack about XSLT so I went with HTML. I am adding an XML backend, so you will be able to produce raw XML if that tickles your fancy.
- I like the lay-out that I kinda ripped from Ben better :P But that's just a matter of stylesheet of course ;)
Well, my layout is my personal twist on a rip-off of your ripped off version of Ben's layout ;)

It's more just a "default look" until things are working properly.
"I don't know why a refrigerator is now involved, but put that aside for now". - Jim e on unitedti.org

avatar courtesy of driesguldolf.
User avatar
qarnos
Maxcoderz Staff
Posts: 227
Joined: Thu 01 Dec, 2005 9:04 am
Location: Melbourne, Australia

Post by qarnos »

I've uploaded a new snapshot of the 3D engine documentation using EGADS - Easy Generation of Assembly Documentation from Source.

There are a few "test" routines - console.* - thrown in to check that the generator handles period separated names correctly. Check out the documentation for "console" and "console.writeln" to see what I am talking about.

link.
"I don't know why a refrigerator is now involved, but put that aside for now". - Jim e on unitedti.org

avatar courtesy of driesguldolf.
User avatar
Timendus
Calc King
Posts: 1729
Joined: Sun 23 Jan, 2005 12:37 am
Location: Netherlands
Contact:

Post by Timendus »

qarnos wrote:I don't know jack about XSLT so I went with HTML. I am adding an XML backend, so you will be able to produce raw XML if that tickles your fancy.
- I like the lay-out that I kinda ripped from Ben better :P But that's just a matter of stylesheet of course ;)
Well, my layout is my personal twist on a rip-off of your ripped off version of Ben's layout ;)
Feel free to use my XSLT sheets and layout -- erm, Ben's layout ;) Once you've generated XML in the Vera fashion (sorry, don't have a DTD for you) it should more or less automagically work with it. I didn't know a thing about XSLT either when I started on it, but I used the Vera documentation as an excuse to learn about it :)

It sounds like your parser is a lot more complex than mine, which is a good thing because I don't plan to work on mine much, though it really needs a few bugfixes and improvements... So if your parser works for our code, and it's more advanced, I've got an excuse to switch and drop development of my own parser ;)

Either way, I don't have a lot of time to spare for Vera anyway...
http://clap.timendus.com/ - The Calculator Link Alternative Protocol
http://api.timendus.com/ - Make your life easier, leave the coding to the API
http://vera.timendus.com/ - The calc lover's OS
User avatar
benryves
Maxcoderz Staff
Posts: 3087
Joined: Thu 16 Dec, 2004 10:06 pm
Location: Croydon, England
Contact:

Post by benryves »

I ripped the layout off from the VS2005 MSDN library. :roll:

Looking good, though. :)
Post Reply