On source conventions and documentation [Release!]

A General Discussion forum for TI calculators

Moderator: MaxCoderz Staff

User avatar
benryves
Maxcoderz Staff
Posts: 3087
Joined: Thu 16 Dec, 2004 10:06 pm
Location: Croydon, England
Contact:

Post by benryves »

Timendus wrote:I understand I can safely throw my implementation out of the window as soon as Brass 3 comes out ;) When do you plan/hope to release it?
When It's Done. ;) Soon, hopefully (for testing). Still a few missing features (like reusable labels) and poorly implemented ones (eg loading two plugins with the same name).

I wouldn't recommend throwing out your implementation, though. The more the merrier :)
Documented name doesn't match compiled name (console.xyz in documentation, Console.XYZ in source).
This should be an error (as it produces incorrect documentation for case-sensitive compilers)
File doesn't have an end of file marker.
This should be a warning though; I don't think it shouldn't compile just because there's no end of file marker - people outside our project will not like that kind of behaviour from their compiler :)
The compilation process is reset state->first pass->reset state->second pass->generate output file->generate listing files. So, if a listing file generator (like the "veradoc" plugin) raises an error it won't affect the output of a valid binary.
Concerning the routine, variable, constant thing; are we sure that those are the three things we want? Is that a logical distinction to make? In a way we now have "file" and "routine", it would make sense to add predefined memory locations to it (like saferams), I suppose that's what you have in mind with "variables"? And "constants" are things like val = 123 that don't point to locations in memory but define some value (link port writes, things like flags and stuff)?
Yes, that's exactly how I saw it, though your comment raised another point; are "saferams" really variables? In some instances they are (plotsscreen and savesscreen are both bitmap variables). :\ Maybe have them as variables but call their type "scratchpad" or something?
It would be fairly annoying to have to define every constant like this:

Code: Select all

;; ### LINKPORT ###
;; 
;; Defines the port that you need to write to for changing the
;; current of the link port lines
;;
;; Value:
;;    0

LINKPORT = 0
Especially if we have a lot of them in something like vera.inc. And it would be completely pointless, seeing that most of the information is already in the statement LINKPORT = 0. Maybe we could allow that, but also allow to abbreviate that a bit to something like:

Code: Select all

;; -###-
;; Defines the port that you need to write to for changing the
;; current of the link port lines
LINKPORT = 0
And have the docgen extract the name and the value automagically?
Yes, that would make sense (and to logically extend it to routines as well).
(Of course, this would be hell for my parser, but seeing that Brass parses everything anyway..?)
Indeed :(
User avatar
Timendus
Calc King
Posts: 1729
Joined: Sun 23 Jan, 2005 12:37 am
Location: Netherlands
Contact:

Post by Timendus »

benryves wrote:I wouldn't recommend throwing out your implementation, though. The more the merrier :)
You're probably right... Not everyone assembles with Brass I guess :)
I've added the routine overview last friday, still needs a few bugs fixed but it's looking good.
The compilation process is reset state->first pass->reset state->second pass->generate output file->generate listing files. So, if a listing file generator (like the "veradoc" plugin) raises an error it won't affect the output of a valid binary.
What then is the difference between an error and a warning? :)
your comment raised another point; are "saferams" really variables? In some instances they are (plotsscreen and savesscreen are both bitmap variables). :\ Maybe have them as variables but call their type "scratchpad" or something?
Hmm, I'd be in favour of just grouping the lot together under the name "variable". None of them really are variables in the usual sense of the word, but I don't expect many people to care, and we don't really use variables/constants very often. In other words; I doubt it's worth our time and effort to sort them all out, name them, and implement their definitions in our documentation generators...
Yes, that would make sense (and to logically extend it to routines as well).
I'm not sure I'd use that for routines as well, for the sake of human readability. Routine headers are typically a lot more complex than the small description that a variable needs, and I think it's a good thing to state which routine you're describing at the beginning of the comments. (Also, they take a lot longer to code, so adding more complex headers is a natural thing to do)
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
Timendus
Calc King
Posts: 1729
Joined: Sun 23 Jan, 2005 12:37 am
Location: Netherlands
Contact:

Post by Timendus »

Current Vera documentation with fancy routine overview:
http://timendus.student.utwente.nl/~vera/asmdoc/
(Has only been tested with Firefox, but is expected to work)

I'll try to build a new Windows binary one of these days so I can release v1.5, which fixes an ugly bug in v1.4 that made it produce invalid XML in some cases, and adds the routine overview.
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 »

Timendus wrote:What then is the difference between an error and a warning? :)
Presentation, once again. :) Usually a warning is something that isn't hugely important to the workings of the project and an error is something that is clearly wrong. Both should be fixed, though.
(Has only been tested with Firefox, but is expected to work)
Consider it tested in Opera 9 and IE7 too. Looks great. :D

(Though I'm not still convinced by the mix of serif/sans-serif fonts)...
User avatar
Timendus
Calc King
Posts: 1729
Joined: Sun 23 Jan, 2005 12:37 am
Location: Netherlands
Contact:

Post by Timendus »

Yes, I need to fix those fonts... but my current workstation doesn't have all the fancy Windows fonts, so that'll have to wait. And of course it's of a lesser priority.
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
Timendus
Calc King
Posts: 1729
Joined: Sun 23 Jan, 2005 12:37 am
Location: Netherlands
Contact:

Post by Timendus »

New version: Asmdoc v1.5.

Added routine overview in the bottom left corner of your browser window, fixed an ugly bug in the parser.

Edit: Archive is broken... fucked up network here is screwing with my upload... trying to fix...
Edit2: I give up, it's just not working... I'll try again after the weekend.
Edit3: Got it on my server! Go download it, and let me know what you think ;)
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 »

Hey, I just saw this Timendus! Great work.

I have been intending on writing something like this for the 3D engine. I have been using a fairly standard commenting syntax throughout, and would like to use that to generate the documentation.

I'm loathe to translate all my comments to the new format, but it will be easier than writing a tool as cool as this.

I'll try it out sometime this weekend.
"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 »

Thanks! That's a pretty good idea I think, seeing that interfacing with someone else's 3D engine is complex enough WITH documentation ;)

You can probably just do a few "replace all"s, or write a small Perl script to change your comments to this format?

(What is your format, by the way? Perhaps we can learn something from it :))
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:Thanks! That's a pretty good idea I think, seeing that interfacing with someone else's 3D engine is complex enough WITH documentation ;)

You can probably just do a few "replace all"s, or write a small Perl script to change your comments to this format?

(What is your format, by the way? Perhaps we can learn something from it :))
Actually, my comment format is quite similar to yours, which will make converting easier. I'll probably just do a manual conversion, which will give me a chance to make sure all the information is correct.

To take an example from the engine code:

Code: Select all

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;
;; alMakeFrustumCode:
;;
;;  Generates an "out-code" for a 16-bit 3D vector for use by the 3D
;;  clipping routines. This code is simply a series of bit flags indicating
;;  whether a point is "in" or "out" of a particular plane. Therefore, an
;;  out-code of zero indicates the point is entirely "in".
;;
;;  The Z distance of the near and far frustum planes are stored in the
;;  variables g_al3DClipNear and g_al3DClipFar.
;;
;;  The bottom and left planes are defined as -Z and the top and right planes
;;  are defined as +Z, where Z is the z-value of the co-ordinate being tested. 
;;
;; INPUTS:
;;  HL - address of 16-bit vector
;;
;; OUTPUTS:
;;  A  - Frustum out-code.
;;
;; DESTROYED:
;;  BC, DE
;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
There really isn't that much difference to the routine header comments.

When it comes to general comments, I usually break my routines up into small blocks each with their own header comment, and also with minor comments to the right of the code, like this:

Code: Select all

            ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
            ;; Load Z Vector into BC.
            ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
            push    bc                      ; [11]
            push    de                      ; [11]
            ld      bc, 5                   ; [10] offset hl to last byte.
            add     hl, bc                  ; [11]
            ld      b, (hl)                 ; [7] load Z value from (hl).
            dec     hl                      ; [6]
            ld      c, (hl)                 ; [7]
            ex      de, hl                  ; [4] input <-> undefined
      
            ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
            ;; Test Z vector against NEAR plane.
            ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
            xor     a                       ; [4]
            ld      hl, (g_al3DClipNear)    ; [20]
            adc     hl, bc                  ; [15]
            jp      p, $ + $0005            ; [10] jump if inside the frustum.
            set     f_alFPlaneNear, a       ; [7] set out flag.
The best piece of advice I have ever received is to comment your code for the third person - as if you were trying to explain the code to someone else.

Thanks to the heavy commenting, I have been able to jump straight back into the project even after a year of not working on it. It's certainly worth the effort.
"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:The best piece of advice I have ever received is to comment your code for the third person - as if you were trying to explain the code to someone else.

Thanks to the heavy commenting, I have been able to jump straight back into the project even after a year of not working on it. It's certainly worth the effort.
Heh, I keep trying to explain that to people, but it seems you really have to find out for yourself... :)

If you have any comments on the docgen tool, or suggestions, please let me know.
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:
qarnos wrote:The best piece of advice I have ever received is to comment your code for the third person - as if you were trying to explain the code to someone else.

Thanks to the heavy commenting, I have been able to jump straight back into the project even after a year of not working on it. It's certainly worth the effort.
Heh, I keep trying to explain that to people, but it seems you really have to find out for yourself... :)

If you have any comments on the docgen tool, or suggestions, please let me know.
Well, I just had my first play around with it. :)

It looks very promising and I'd love to use this for my documentation but it has a few problems parsing my source.

The main one seems to be it getting confused with my regular comment syntax (I think it's all those semicolons). The solution which is obvious to me would be some kind of marker to turn the Vera parser on/off.

The other thing I would love would be a clobber-list for registers which are destroyed by a routine. I think it's important enough to have a separate section rather than just lumped under postconditions. Or perhaps I'm just to attached to the INPUTS/OUTPUTS/DESTROYED thing. :D

One other minor thing - and I'm being very nitpicky here - IMHO, a better way to indicate an internal routine would be a pair of equal signs rather than single semicolons. Like this:

Code: Select all

;; === External.routine ===
;; == Internal.routine ==
I only say that because to me it breaks the visual flow of the source to have some sections double-semi-coloned and other only single. I'm a bit of a pain like that - I like my source to look pretty and consistent :D

In any case - excellent work. This could make life a lot easier.
"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:The main one seems to be it getting confused with my regular comment syntax (I think it's all those semicolons). The solution which is obvious to me would be some kind of marker to turn the Vera parser on/off.
Double semicolons on the first two columns mark that the Vera parser should do something with that line. We considered that enough of a marker :) If it chokes on a line with nothing but lots of semicolons that could be considered a bug though... I'll add it to the list of things to be looked at, thanks! :)
The other thing I would love would be a clobber-list for registers which are destroyed by a routine. I think it's important enough to have a separate section rather than just lumped under postconditions. Or perhaps I'm just to attached to the INPUTS/OUTPUTS/DESTROYED thing. :D
Well, I think the difference lies in the naming. We call them preconditions and postconditions, not inputs and outputs. And as such, a precondition could be that the graph buffer should have been cleared, which has nothing to do with input registers. Same goes for destroyed registers; they're a postcondition. Obviously we've nicked the concepts from higher languages, and forced them on assembly, which you could argue is a stupid thing to do, but it's served us nicely so far :)

(Also, you could argue that destroying a register results in some output, be it zero or "undefined", it's still output ;))

I think we should add a "Bugs" tag though, I've needed those on several occasions to remind myself and others of bugs and unfinished code. And I'm starting to think that code-centered bugtracking could be better for Vera than using some web application.

(Perhaps you could call destroyed registers "bugs"? :mrgreen:)
One other minor thing - and I'm being very nitpicky here - IMHO, a better way to indicate an internal routine would be a pair of equal signs rather than single semicolons.
Like I said; double semicolons are the marker for the Vera parser to do something with the specified line. So when we use the same format for internal routines, but without the double semicolons we're basically just doing that for human readability, and skipping the parser, we're not telling it that it's an internal routine. (In other words: the parser has no concept of internal routines.)

If you're used to having double semicolons everywhere, I can imagine it to be a pain that we've chosen that as our marker, and I'm sorry for that, but you're the first person I see doing that :?
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:Like I said; double semicolons are the marker for the Vera parser to do something with the specified line. So when we use the same format for internal routines, but without the double semicolons we're basically just doing that for human readability, and skipping the parser, we're not telling it that it's an internal routine. (In other words: the parser has no concept of internal routines.)
Ahhh... I see. I assumed the parser was generating some kind of documentation for internal routines. No problem, then. :)
If you're used to having double semicolons everywhere, I can imagine it to be a pain that we've chosen that as our marker, and I'm sorry for that, but you're the first person I see doing that :?
I thought it looked nicer than single semicolons! :P
"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 »

Just another quick note -

It seems that when parsing, once it has found a line with double semi-colons, it will parse the following lines even if they have only one semi colon and there are no blank lines between them.

Example:

This:

Code: Select all

;; === alSetProjectionWindow ===
;;
;;  Sets the size and position of the projection window used by alProject.
;;
;; Pre:
;;  BC - Top-left corner of projection window, screen coordinates (x, y)
;;  DE - Bottom-right corner of projection window, screen coordinates (x, y)
;;
;; Post:
;;  AF, BC, DE, HL destroyed.
;;
; test
; test
; test
Produces this in the docs:

Code: Select all


Postconditions:
    AF, BC, DE, HL destroyed
    ; test
    ; test
    ; test

"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 »

Woops :mrgreen:

That probably has something to do with the "state machine" being in the Postconditions state and not checking for the marker properly... I know it works for file/routine descriptions. Just add an empty line in between for the moment, I'll take a look at it ;)
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
Post Reply