gap span threshold - Uncrustify Documentation Project

Uncrustify use the words « gap », « span » and « threshold » in a way that some people find confusing.

The uses

The uses are fairly homogenous:

11 options are using gap (align_xxxx_gap).
They all take a numerical value in [0 .. 16], 0 being the default value.
No exceptions.
18 options are using span (align_xxxx_span)
They all take a numerical value in [0 .. 5000], 0 being the default value.
Exceptions:
- align_constr_value_span and align_typedef_span are in [0 .. 16].
- align_func_proto_span_ignore_cont_lines is a boolean.
12 options are using thresh or threshold (align_xxxx_thresh)
They all take a numerical value in [-1000 .. 5000], 0 being the default value.
A positive value is a relative value, a negative value is used as an absolute value.
Exceptions:
- indent_comment_align_thresh is in [0 .. 16], 3 being the default value.
- indent_func_def_param_paren_pos_threshold is in [0 .. 160].

gap: A 'gap' is the minimum spacing for aligned items.
So, if it is set to 3 for typedefs, then there are a minimum of three spaces between the type and the typedef name.
span: A 'span' is the maximum number of lines that an aligning feature will be considered.
This is done to limit the scope of the aligning. So, if a span is set to 3 and more than 3 lines do not contain the item that is to be aligned, then the aligning set is closed.
threshold: A 'threshold' is the maximum number of columns that an aligning feature will be considered.
This is done to limit the scope of the aligning. This prevents really longs lines from being aligned with short lines.

1/ Do these two definitions help you to understand what xxxx and yyyyy are?

A 'xxxx' is the maximum number of lines that an aligning feature will be considered. This is done to limit the scope of the aligning.
A 'yyyy' is the maximum number of columns that an aligning feature will be considered. This is done to limit the scope of the aligning.

NO!
The only thing you can say is that xxxx is about lines and yyyy is about columns.
But you can't say which is a 'gap', a 'span' or a 'threshold'.

2/ The confusion is also due to the usage of maximum or minimum in all three definitions.
If there is a upper or lower limit this is a threshold.

3/ More generally, the explanations for many options are very short and sometime cryptic.

It seems to me that, when it comes to alignment, uncrustify uses these 3 words in a suitable but restrictive context:

‘gap’ as a minimum number of space.
‘span’ as maximum number of line.
‘threshold’ as a maximum number of space. See this interesting document about threshold.

The technical restrictions (minimum/maximum) and (space/line) are more important than the English definition.