Making adjustments using source code directives

To make adjustments by marking them in your code:

1. Embed adjustment directives as comments in your source code.

2. Then extract the directives and apply them in calculating coverage data.

Embedding adjustment directives

Each directive is a comment consisting of the keyword purecov followed by a colon (:), and then the type of adjustment.

Two styles of directives are available:

• single-line, each of which affects one line of code

• block, which indicate the beginning and end of an adjusted block of lines

Directive	Meaning
For deadcode    Single-line style       /* purecov: deadcode */    Block style       /* purecov: begin deadcode */      /* purecov: end */	The indicated lines are not reachable, even in theory.
For tested code    Single line style       /* purecov: tested */    Block style       /* purecov: begin tested */      /* purecov: end */	The indicated lines have been tested by someone, at some point, and should be considered as working.
For inspected code    Single-line style       /* purecov: inspected */    Block style       /* purecov: begin inspected */      /* purecov: end */	The indicated lines have been through some kind of code inspection or review, and are believed to be correct.

For example, the following line is marked as deadcode:

printf("bar!\n"); /* purecov: deadcode */

If you use begin and end pairs, the adjustment applies to the lines containing the comment, as well as all lines in between.
 

Notes:
 

• When you do not conclude a begin block comment with an explicit end comment, PureCoverage uses the line of the EOF as the missing end line. Note that if the file grows, this adjustment still extends only to the old EOF unless you extract the adjustments from the file again.

• The begin and end pairs do not nest, even if they are the same type of adjustment. It is not necessarily an error for a begin to exist without a matching end: Everything in the file after the begin is adjusted. However, a warning that there is no corresponding end appears on the output.

• Directives are recognized wherever they occur, even if they are not in comments.

• If there is no code on an adjusted line, the adjustment has no effect on the coverage data, so there is no danger in something like this:
  
  /* $Log: myfile.c,v $
  * Revision 2.54 1999/01/16 12:32:02 frodo
  * added "purecov: deadcode" directives
  */ 
  
  Be aware, however, that PureCoverage also suppresses a line like this: 
  
  printf("/* purecov: deadcode */\n");

• If you mark an unnecessary adjustment, PureCoverage indicates it by highlighting the three adjustment columns (D, I, and T) for the line in the Annotated Source window.

Extracting adjustments from source files

PureCoverage extracts adjustments from an individual file automatically when you open the Annotated Source window for that file.

To extract adjustments from all files referenced in the PureCoverage Viewer:

• Select Adjustments > Extract adjustments from all source files in the PureCoverage Viewer.

• Or use the command purecov -extract *.c before opening the Viewer. This extracts all adjustments from all source files and stores them in ~/.purecov.adjust.

Extract the adjustments each time the source file is modified. You can do this automatically by adding the -extract option in the makefile as part of the cc -c step.

Whenever PureCoverage extracts adjustments, it outputs a short summary of the extraction process. For example:

% purecov -extract bim.c
Updating adjustments for /canonical/path/to/bim.c:
     23 lines of dead code
     42 manually tested lines

When you open the PureCoverage Viewer, PureCoverage applies the adjustments in ~/.purecov.adjust to the display. The adjustments are reflected in:

• the PureCoverage Viewer

• the Annotated Source window, where you can make additional adjustments interactively

Saving adjustments

You can save the adjustments you have made in the source file and in the adjustments file ~/.purecov.adjust by selecting File > Save in the Annotated Source window.