lazarus/components/jcf2/docs/special_comments.md

Special comments in the Jedi Code Formatter

The code formatter now  recognizes certain comments  to disable and enable formatting options around blocks of code.

Since the earliest versions, the comments {(*} and {*)} could be used to disable and reenable formatting respectively, in order to exclude a block of code from formatting. 

From version 0.52, a more extensive syntax has been implemented to allow for fine-grained control over which formatting options are temporarily disabled. The original special comments {(*} and {*)} are retained as synonymns for //jcf:format=off and //jcf:format=on  respectively.

For instance, in the following line of code, the formatter will not alter the spacing

//jcf:space=off
  a   :=     a     +     1   ;
//jcf:space=on

As you can see, the new syntax has the form of a comment like //jcf:**flag**=**state**, where state is one of on or off, and the flags are listed below.

Flags

Flag	Description
parse	Stop parsing tokens (to avoid errors on unsupported code)- to turn it on again need jcf:parse=on (since lazarus 3.99)
all	all=on is used to reverse the effects of all off comments (except parse), as described below. all=off is not valid
format	All formatting (except parse)
space	All processes that insert or remove spaces
addspace	All processes that insert spaces
removespace	All processes that remove spaces
return	All processes that insert or remove returns
addreturn	All processes that insert returns
removereturn	All processes that remove returns
add	All processes that insert spaces or returns
remove	All processes that remove spaces or returns
align	All processes that align statements - i.e. alignment of variables, constants, types and assignment statements
aligndef	Alignment of variables, constants and types
alignfn	Alignment of variables and assignments
alignvars	Alignment of variables
alignconst	Alignment of constants
aligntypedef	Alignment of types
alignassign	Alignment of assignment
indent	Correct block indent of statements and declarations
caps	Capitalisation of reserved words or user-specified words
capsreservedwords	Capitalisation of reserved words
capsspecificwords	Capitalisation of user-specified words
linebreaking	Breaking of long lines
blockstyle	Line-breaking in blocks of statements
warnings	Warnings generated by the code fornatter
warnassigntofunctionname	Warning asign to function name (since lazarus 3.99)
warncasenoelse	Warning case has no else (since lazarus 3.99)
warnemptyblock	Warning empty block (since lazarus 3.99)
warnunusedparam	Warning unused param (since lazarus 3.99)
findreplace	Find and replace
findreplaceuses	Maniupulation of the uses clause

The following rules apply:

• Turning a flag on will not enable it if it is not enabled in the configuration - the flags are to 'block out' a section of code where a format option is not wanted. The on state is there only to end a previous off state.
• All processes (except parse) turned off by a flag comment remain turned off until the corresponding flag comment that turns it back on is reached, or the end of the file is reached, or the flag comment //jcf:all=on is reached.
• The flag comment //jcf:all=on will reenable all processes that have been turned off by comments, ie it returns formatting to the options specified in the configuration (except parse).
• Flag comments only affect the file in which they occur, from the position in which the occur onwards.
• The effects of some of the flags overlap - this is done to allow degrees of granularity e.g. turn off all alignment, or just alignment of variable declarations for a block of code.
• In these special comments, character case and some spaces are ignored.
• A comment that starts with //jcf: but cannot be recognised as one of the options given will cause a warning in the log but will have no effect of the file's format.

For examples see the test case unit TestExclusionFlags.pas, for implmentation see the unit FormatFlags.pas

---