Documentation Standards - Procedures

Each procedure that you hand in should contain a block comment at the top of it that gives a brief description of what the procedure does. Typically, this block should be 1-2 sentences in length, but use your judgement. Additionally, you should have a list of preconditions, post-conditions, and any remarks about the procedure. Possible remarks include all registers are returned to their original states, registers ax, bx, ... are modified, or a list of error codes if an error code is returned. A good post-condition would be the carry flag being set if an error occured. What goes where is not too critical - but be consistant. A few examples of program level comments are given below. Please note that the TITLE key word and file name are given. That is because all of these procedures are pulled from library modules. Each module (procedure) is in its own file, hence the filenames. Don't worry about this right now, but you will want to follow a format similar to this later on.

TITLE killTime.ASM
;=======================================================================
; killTime is a function designed to waste a large amount of time
;=======================================================================
;   PreCond  -- None
;   PostCond -- This task will run indefinately
;   Remarks  -- All registers are returned to their original states.
;=======================================================================


TITLE chgPtry.ASM
;=======================================================================
; changePriority toggle between MIDDLE and HIGHEST priority
;       LOWEST priority is reserved for the dummy task
;=======================================================================
;   PreCond  -- AL = taskID to modify
;   PostCond -- The task's priority is modified
;   Remarks  -- All registers are returned to their original states.
;=======================================================================

Other possible comment blocks are shown below. (You can choose how you want to comment your code, but your method should be consistant, quick to do, and most importantly, readable).

;=======================================================================
; QPtChrs will write a character n times to the screen at the current
;       cursor location (This code has been minimized for the TTT proj)
;=======================================================================
;   PreCond  -- AH=number of times to print the character
;               AL=Character to print
;   PostCond -- The character will be printed AH times to teh screen
;               starting at the current cursor position
;               NOTE: the cursor will not be advanced!!!
;=======================================================================
;   Saves       |        Uses        |        Modifies
;-----------------------------------------------------------------------
;   CX, BX      |      AX, BX, CX    |       AX, BX, CX
;=======================================================================



COMMENT     #       PROCEDURE HEADER
PURPOSE:            Writes the ASCIIZ string to STDOUT
CALLED AS:          strOut (String)
                    where String is a null terminated string (ASCIIZ)
                    pointed to by DS:SI and the handle is on the top
                    of the stack.
REMARKS:            strLen.INC must be included for this to work
                    If an error occurs, the carry flag will be set
                    and AX will contain the error code otherwise
            #       AX will contain the number of characters written

Reminder: when printing source code, please use Courier or some other fixed width font.