pub enum Layout {
Lines,
Columns,
Compact,
}Expand description
What a removal leaves behind in place of the comment.
The choice is only about the hole: no layout moves a byte the comment did not cover, except where the hole itself would say something. That happens in one place, and it is YAML.
A block scalar decides where its body ends from the lines below it
(YAML 1.2.2, 8.1.1), so a whole-line comment under a body is what
terminates it — and the hole a removal would leave on that line is read
back as content. A line of spaces as wide as the comment, which columns
writes, is indented at least as deep as the body whenever the comment was
wide enough; an empty line, which lines writes, is content under |+ and
>+, which keep every empty line trailing a body (8.1.1.2). So in YAML a
whole-line comment sitting in the run of blank and comment lines under a
block scalar body is removed by taking its whole line, terminator and all,
under every layout: lines gives up that line’s number and columns
its columns, rather than give up the value. Under |+ and >+ the removal
also takes the blank lines the comment was sheltering — they are content
the moment it is gone — and never the blank lines above the first comment,
which were content already.
Variants§
Lines
The default. The line terminators inside the comment are kept, so every following line keeps its number, and a comment with code on both sides leaves a single space so the two tokens stay apart. The YAML exception above is the one place a line does not keep its number.
Columns
As Self::Lines, but the comment is replaced by spaces of the same
display width, so every following column on the line keeps its number
as well. Tabs are expanded to the next multiple of eight. A line of
spaces under a YAML block scalar body is indented into it, so the YAML
exception above applies here too — and reaches further, because it
applies whatever the block scalar chomps.
Compact
As Self::Lines, except that a line which held nothing but a
removed comment goes away instead of staying behind as a blank one,
and the whitespace a removal would leave at the end of a line is
trimmed away with it.
Code keeps its own lines. A comment that shared a line with code leaves that line, its terminator and its CRLF or LF style exactly as they were, so a comment running across several lines with code before or after it closes up to one line rather than joining two statements. A surviving line keeps the ending it had in the source — the same LF or CRLF, from inside the comment if that is where it was — or no ending at all if the file stopped there without one.
Being alone on a line is judged from the original bytes, so a line holding two comments and nothing else keeps its terminator: neither comment was alone on it.