ReturnCount: Make configuration parameter more explicit

[TWiStErRob]

Background

I want to configure ReturnCount to ignore Android's onMenuItemSelected and onOptionsItemSelected because they should have many returns to prevent bugs and strange behavior.

Problem

In the JSON-schema we have this definition:

            "excludedFunctions": {
              "type": "string"
            },

Stringly typed items are hard to use, because they don't define structure.
It's not clear if this string is a regex, or a pipe separated list, or a comma separated list, or even a semi-colon separated regex list.

Investigation

Note: this investigation has to be done by anyone who wants to use this configuration, and they might not know how to navigate the code or not have will.

Docs

https://detekt.dev/docs/rules/style/#returncount

No conclusive result.

Source code

detekt/detekt-rules-style/src/main/kotlin/io/gitlab/arturbosch/detekt/rules/style/ReturnCount.kt

Lines 62 to 63 in 1b330e9

	@Configuration("define functions to be ignored by this check")
	private val excludedFunctions: SplitPattern by config("equals") { SplitPattern(it) }

Now I know it's split somehow.

Tests

detekt/detekt-rules-style/src/test/kotlin/io/gitlab/arturbosch/detekt/rules/style/ReturnCountSpec.kt

Line 350 in a2734b1

EXCLUDED_FUNCTIONS to "test1,test2"

Now I know it's split by comma.

Deeper look

detekt/detekt-rules-style/src/main/kotlin/io/gitlab/arturbosch/detekt/rules/style/ReturnCount.kt

Line 93 in 1b330e9

private fun shouldBeIgnored(function: KtNamedFunction) = excludedFunctions.contains(function.name)

calls

detekt/detekt-api/src/main/kotlin/io/gitlab/arturbosch/detekt/api/SplitPattern.kt

Line 31 in 1b330e9

fun contains(value: String?): Boolean = excludes.any { value?.contains(it, ignoreCase = true) == true }

also

detekt/detekt-api/src/main/kotlin/io/gitlab/arturbosch/detekt/api/SplitPattern.kt

Lines 65 to 70 in 1b330e9

	fun String.commaSeparatedPattern(vararg delimiters: String = arrayOf(",")): Sequence<String> {
	return this
	.splitToSequence(*delimiters)
	.filter { it.isNotBlank() }
	.map { it.trim() }
	}

Now I know it's definitely comma separated (from constructor default parameter), and that it's case insensitive (which is strange in a strongly typed case sensitive language), I also know the comma separated list is free-from because of trim and resilient in case there are multiple or trailing commas.

Solution

Update docs to reflect this.

Note

Obviously a more explicit way of doing this would be ideal:

    excludedFunctions:
      # Ignore MenuProvider.onMenuItemSelected,
      # because it has a special structure for bug prevention.
      - onMenuItemSelected
      # Ignore Activity.onOptionsItemSelected and Fragment.onOptionsItemSelected,
      # because they has a special structure for bug prevention.
      - onOptionsItemSelected

but for now, this will do:

    excludedFunctions:
      # Ignore MenuProvider.onMenuItemSelected, Activity.onOptionsItemSelected,
      # and Fragment.onOptionsItemSelected, because they have a special structure for bug prevention.
      '
        onMenuItemSelected,
        onOptionsItemSelected,
      '

[TWiStErRob]

re "free-form": https://en.wikipedia.org/wiki/Free-form_language

In computer programming, a free-form language is a programming language in which the positioning of characters on the page in program text is insignificant. Program text does not need to be placed in specific columns as on old punched card systems, and frequently ends of lines are insignificant.

[BraisGabin]

Interensting... this shouldn't be a String this should be a List<String>.

[TWiStErRob]

Different issue ;) in here I just wanted to focus on improving the docs.

[TWiStErRob]

But on a related note: ForbiddenImport has the same problem, but there it's on the happy path, not an exceptional setup.

[BraisGabin]

Why do you say that ForbiddenImport has that issue? It shouldn't.

[TWiStErRob]

ForbiddenImport was changed in v1.18.0-RC1 by 8e1328a, and we're on 1.18.1 and it still uses a single string, and it works, but anyway, I see in the JSON schema it's now an array and also it's history now :)