Software engineering #2- Documentation

RTFM,

With the first function written comes the issue of the documentation. ASM needs a lot of documentation. But after some try, it turns out that just commenting the code is not enough. There is not enough place to write all the informations needed.

So I decided to put the documentation in another file (See here for a copy of it https://github.com/PainsPerdus/gboi-rocket/wiki/collision-doc).

The documentation of a function first contains a label (useful if you want to call the function ), the parameters (with all informations needed like the names, size, struct, description…), the return value (how it is returned, the meaning, representation…).

After that come secondary informations (but I am ready to kick the ass of any slob who would make a pull request without documenting those) about the execution of the function. The values modified by the execution of this function (May I never find a callee saved register in this section…), the global variables used if there is any, the struct used, the memory locations, labels, etc used by this function.

And last but not least, the pseudo code of the function. Preferably written in C, with comments linking section of this code to sections of the assembly code. A high level explanation of the code has to be added if needed.

The assembly code has to be commented as well, but the comments aim to explain the transition from assembly to C. More informations are welcome but not mandatory as long as the link between the sections of assembly and the sections of pseudo code in the documentation is clear.

I can help but feel like I forgot something in the informations needed in the doc. Assembly leaves no place for imprecision… Well, for now that should do . The only comments I had with it was about the syntax I use to define sections in my code. We haven’t agreed yet btw…

JM