Policies and layouts

Two settings decide what a run does, and they are independent of each other. A policy decides which comments may be removed at all. A layout decides what is left behind where a removed comment used to be. Both are available as --policy and --layout on the command line, as mode and layout under [policy] in .ocomment.toml, and as policy and layout on an [[overrides]] entry that matches a path.

Every before-and-after pair on this page was produced by running the sample below through ocomment strip, so the outputs are the real bytes, trailing spaces included.

The sample

// SPDX-License-Identifier: MIT OR Apache-2.0

// rustfmt::skip
/// Adds two numbers.
pub fn add(a: u32, b: u32) -> u32 {
    let total = a + /* NOTE: widen */ b; // TODO: check for overflow
    /* NOTE: Everything from here down is one block comment
       that runs across three lines, so each layout has
       something to show. */
    total
}

It carries a licence header, a tool directive, a documentation comment, an inline block comment between two tokens, a trailing comment, and a block comment that spans several lines.

What each policy removes

Each of these is ocomment strip --language rust --policy <mode> reading the sample on standard input.

`none`

// SPDX-License-Identifier: MIT OR Apache-2.0

// rustfmt::skip
/// Adds two numbers.
pub fn add(a: u32, b: u32) -> u32 {
    let total = a + /* NOTE: widen */ b; // TODO: check for overflow
    /* NOTE: Everything from here down is one block comment
       that runs across three lines, so each layout has
       something to show. */
    total
}

`conservative`

// SPDX-License-Identifier: MIT OR Apache-2.0

// rustfmt::skip
/// Adds two numbers.
pub fn add(a: u32, b: u32) -> u32 {
    let total = a +  b; 
    


    total
}

`standard`



// rustfmt::skip

pub fn add(a: u32, b: u32) -> u32 {
    let total = a +  b; 
    


    total
}

`all`





pub fn add(a: u32, b: u32) -> u32 {
    let total = a +  b; 
    


    total
}

none is the mode for a repository that wants the style rules and not the removals: it returns the sample unchanged. conservative and standard differ over the licence header alone, and all is the only one that takes the // rustfmt::skip directive out. all still refuses to touch a shebang or an encoding preamble until --force-protected is given as well; see Why was this comment kept?.

What each layout leaves behind

Each of these is ocomment strip --language rust --layout <layout> reading the same sample, under the default conservative policy.

`lines`

// SPDX-License-Identifier: MIT OR Apache-2.0

// rustfmt::skip
/// Adds two numbers.
pub fn add(a: u32, b: u32) -> u32 {
    let total = a +  b; 
    


    total
}

`columns`

// SPDX-License-Identifier: MIT OR Apache-2.0

// rustfmt::skip
/// Adds two numbers.
pub fn add(a: u32, b: u32) -> u32 {
    let total = a +                   b;                            
                                                           
                                                       
                            
    total
}

`compact`

// SPDX-License-Identifier: MIT OR Apache-2.0

// rustfmt::skip
/// Adds two numbers.
pub fn add(a: u32, b: u32) -> u32 {
    let total = a +  b;
    total
}

lines and columns keep the line count of the file: a comment that spanned three lines is replaced by something that still spans three lines, so a line number in a stack trace or a git blame still points at the same statement. columns additionally keeps every following column in place by padding with spaces, which is what a table of aligned initialisers or a column-sensitive language wants, at the cost of trailing whitespace that a formatter may then remove.

compact is the layout that gives line numbers up. A line that held nothing but a removed comment goes away with it, terminator included, and the whitespace a removal would leave at the end of a line is trimmed. Code keeps its own lines: a comment sharing a line with code leaves that line, its terminator and its CRLF or LF style as they were. 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.

Which one a formatter accepts

compact, and only compact. This is measured rather than argued: rust/ocomment-core/tests/layout_format.rs strips a source that gofmt and rustfmt already call normal, in every position a comment can sit, and asks each formatter about the result. lines and columns never conform and are not meant to - the empty line and the padding are the promise - so a pipeline that runs gofmt -l or cargo fmt --check beside OComment wants compact.

The test pins that table in both directions, so a layout that stopped conforming fails and so does one that started: the second is a layout that has quietly changed what it promises.

Where they are set

version = 1

[policy]
mode = "conservative"
layout = "lines"

[[overrides]]
paths = ["generated/**"]
policy = "all"
layout = "compact"

The flag wins over the file, and an [[overrides]] entry whose globs match the path wins over [policy]. ocomment config explain prints the resolved values and where each came from, and ocomment --explain names the rule and the setting behind any one comment.

Keyboard shortcuts

OComment