The behaviour of the MISS_HIT tools can
be controlled with pragmas (special comments that can be placed
in the source code). This document describes the syntax and
semantics of the pragmas.
One-line trivial pragmas
Style justification
You can justify style issues by placing a style justification
pragma on the same line the message occurs.
% mh:ignore_style
MISS_HIT Annotation language
Introducing annotations
MISS_IT supports a special annotation language embedded inside
specially formatted MATLAB or Octave comments. An annotation
is introduce using a comment and the bar (this could easily be
made configurable, if there is demand):
%| some_annotation
Annotations span until the end of the line. Annotations can be
multi-line as long as there is no other program text between:
%| pragma Justify (metric, "npath", %| "multi-line example");
Annotation must be the first and only program text on a
line. For example the following program does not contain an
annotation:
x + 1; %| this is not an annotation
Annotations have most of the lexical features of MATLAB,
except that line continuations and command form do not
exist. You can even have comments (but not annotations) in
your annotation:
%| some_annotation; % comment
Expressions
Currently, only static string expressions or direct names are
supported.
a_name ::= IDENTIFIER a_expression ::= a_name | STRING { '+' STRING }
Annotation Pragmas
MISS_HIT annotation pragmas can appear in any place where
normal program statement can occur.
A miss-hit pragma has the following grammar:
annotation_pragma ::= 'pragma' a_name '(' a_pragma_parameters ')' ';' | 'pragma' a_name ';' a_pragma_parameters ::= a_expression { ',' a_expression }
Justification pragmas
A justification pragma has the following signature:
pragma Justify (TOOL, PARAMETER, REASON);Tool identifies the miss_hit tool and can be one of:
- style
- metric
Metric justification pragmas
A metric justification pragma has the following signature:
pragma Justify (metric, METRIC_NAME, REASON);The metric name must be a string to match one of the documented metric names. For example:
%| pragma Justify (metric, "npath", %| "code impossible to restructure");
Tag pragmas
A Tag pragma can be used to tag code (TestTags class/block
parameters already exist to tag unit tests; although you could
also use pragma Tag for this purpose). It has the following
signature:
pragma Tag (STRING [, STRING]+);
For example:
pragma Tag ("PotatoFeature");
Pragma tag applies to all items scoped logically under the
entity that is tagged. For example placing the Tag pragma in a
class definition will affect all methods; placing it in a
function will also affect all nested functions; and placing it
in a compilation unit will affect all functions or methods in
that compilation unit.
No_Tracing pragmas
A No_Tracing pragma can be used to indicate that some code or
test should not be included in the output of mh_trace. It has
the following signature:
pragma No_Tracing;
Pragma No_Tracing has the same scoping rules as pragma Tag.