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 }
Pragma
Currently only a single annotation exists: justification
pragmas. These 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");