Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Don't reformat indent-style comments #1441

Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -233,11 +233,12 @@ class CommentsFormatting(configRules: List<RulesConfig>) : DiktatRule(
}

if (node.elementType == BLOCK_COMMENT &&
(node
.text
.trim('/', '*')
.takeWhile { it == ' ' }
.length == configuration.maxSpacesInComment ||
(node.isIndentStyleComment() ||
node
.text
.trim('/', '*')
.takeWhile { it == ' ' }
.length == configuration.maxSpacesInComment ||
node
.text
.trim('/', '*')
@@ -343,6 +344,30 @@ class CommentsFormatting(configRules: List<RulesConfig>) : DiktatRule(

private fun ASTNode.isChildOfBlockOrClassBody(): Boolean = treeParent.elementType == BLOCK || treeParent.elementType == CLASS_BODY

/**
* Returns whether this block comment is a `indent`-style comment.
*
* `indent(1)` is a source code formatting utility for C-like languages.
* Historically, source code formatters are permitted to reformat and reflow
* the content of block comments, except for those comments which start with
* "&#x2f;*-".
*
* See also:
* - [5.1.1 Block Comments](https://www.oracle.com/java/technologies/javase/codeconventions-comments.html)
* - [`indent(1)`](https://man.openbsd.org/indent.1)
* - [`style(9)`](https://www.freebsd.org/cgi/man.cgi?query=style&sektion=9)
*
* @return `true` if this block comment is a `indent`-style comment, `false`
* otherwise.
*/
private fun ASTNode.isIndentStyleComment(): Boolean {
require(elementType == BLOCK_COMMENT) {
"The elementType of this node is $elementType while $BLOCK_COMMENT expected"
}

return text.matches(indentCommentMarker)
}

/**
* [RuleConfiguration] for [CommentsFormatting] rule
*/
@@ -361,5 +386,10 @@ class CommentsFormatting(configRules: List<RulesConfig>) : DiktatRule(
private const val APPROPRIATE_COMMENT_SPACES = 1
private const val MAX_SPACES = 1
const val NAME_ID = "kdoc-comments-codeblocks-formatting"

/**
* "&#x2f;*-" followed by anything but `*` or `-`.
*/
private val indentCommentMarker = Regex("""(?s)^\Q/*-\E[^*-].*?""")
}
}
Original file line number Diff line number Diff line change
@@ -1,15 +1,21 @@
package org.cqfn.diktat.ruleset.chapter2

import org.cqfn.diktat.ruleset.chapter2.CommentsFormattingTest.Companion.indentStyleComment
import org.cqfn.diktat.ruleset.chapter3.spaces.IndentationRuleTestMixin.describe
import org.cqfn.diktat.ruleset.rules.chapter2.kdoc.CommentsFormatting
import org.cqfn.diktat.util.FixTestBase

import generated.WarningNames.COMMENT_WHITE_SPACE
import generated.WarningNames.FIRST_COMMENT_NO_BLANK_LINE
import generated.WarningNames.IF_ELSE_COMMENTS
import generated.WarningNames.WRONG_NEWLINES_AROUND_KDOC
import org.assertj.core.api.Assertions.assertThat
import org.junit.jupiter.api.Tag
import org.junit.jupiter.api.Tags
import org.junit.jupiter.api.Test
import org.junit.jupiter.api.io.TempDir

import java.nio.file.Path

class CommentsFormattingFixTest : FixTestBase("test/paragraph2/kdoc/", ::CommentsFormatting) {
@Test
@@ -40,4 +46,16 @@ class CommentsFormattingFixTest : FixTestBase("test/paragraph2/kdoc/", ::Comment
fun `regression - should not insert newline before the first comment in a file`() {
fixAndCompare("NoPackageNoImportExpected.kt", "NoPackageNoImportTest.kt")
}

/**
* `indent(1)` and `style(9)` style comments.
*/
@Test
@Tag(COMMENT_WHITE_SPACE)
fun `indent-style header in a block comment should be preserved`(@TempDir tempDir: Path) {
val lintResult = fixAndCompareContent(indentStyleComment, tempDir = tempDir)
assertThat(lintResult.actualContent)
.describedAs("lint result for ${indentStyleComment.describe()}")
.isEqualTo(lintResult.expectedContent)
}
}
Original file line number Diff line number Diff line change
@@ -8,6 +8,7 @@ import org.cqfn.diktat.util.LintTestBase

import com.pinterest.ktlint.core.LintError
import generated.WarningNames
import org.intellij.lang.annotations.Language
import org.junit.jupiter.api.Tag
import org.junit.jupiter.api.Test

@@ -491,4 +492,35 @@ class CommentsFormattingTest : LintTestBase(::CommentsFormatting) {

lintMethod(code)
}

/**
* `indent(1)` and `style(9)` style comments.
*/
@Test
@Tag(WarningNames.COMMENT_WHITE_SPACE)
fun `indent-style header in a block comment should produce no warnings`() =
lintMethod(indentStyleComment)

internal companion object {
@Language("kotlin")
internal val indentStyleComment = """
|/*-
| * This is an indent-style comment, and it's different from regular
| * block comments in C-like languages.
| *
| * Code formatters should not wrap or reflow its content, so you can
| * safely insert code fragments:
| *
| * ```
| * int i = 42;
| * ```
| *
| * or ASCII diagrams:
| *
| * +-----+
| * | Box |
| * +-----+
| */
""".trimMargin()
}
}