Make documentation more precise about how rules are enabled (#3889)

* Make documentation more precise about how rules are enabled

* Update docs/pages/extensions.md

Co-authored-by: M Schalk <30376729+schalkms@users.noreply.github.com>

* Update docs/pages/extensions.md

Co-authored-by: M Schalk <30376729+schalkms@users.noreply.github.com>

* Update docs/pages/extensions.md

Co-authored-by: M Schalk <30376729+schalkms@users.noreply.github.com>

* remove examples that use an EmptyConfig

Co-authored-by: Markus Schwarz <post@markus-schwarz.net>
Co-authored-by: M Schalk <30376729+schalkms@users.noreply.github.com>

detekt-sample-extensions/src/main/kotlin/io/gitlab/arturbosch/detekt/sample/extensions/SampleProvider.kt

@@ -13,7 +13,7 @@ class SampleProvider : RuleSetProvider {
     override fun instance(config: Config): RuleSet = RuleSet(
         ruleSetId,
         listOf(
-            TooManyFunctions(),
+            TooManyFunctions(config),
             TooManyFunctionsTwo(config)
         )
     )

detekt-sample-extensions/src/main/kotlin/io/gitlab/arturbosch/detekt/sample/extensions/rules/TooManyFunctions.kt

@@ -1,6 +1,7 @@
 package io.gitlab.arturbosch.detekt.sample.extensions.rules
 
 import io.gitlab.arturbosch.detekt.api.CodeSmell
+import io.gitlab.arturbosch.detekt.api.Config
 import io.gitlab.arturbosch.detekt.api.Debt
 import io.gitlab.arturbosch.detekt.api.Entity
 import io.gitlab.arturbosch.detekt.api.Issue
@@ -12,7 +13,7 @@ import org.jetbrains.kotlin.psi.KtNamedFunction
 /**
  * This is a sample rule reporting too many functions inside a file.
  */
-class TooManyFunctions : Rule() {
+class TooManyFunctions(config: Config) : Rule(config) {
 
     override val issue = Issue(
         javaClass.simpleName,

detekt-sample-extensions/src/test/kotlin/io/gitlab/arturbosch/detekt/sample/extensions/TooManyFunctionsSpec.kt

@@ -1,5 +1,6 @@
 package io.gitlab.arturbosch.detekt.sample.extensions
 
+import io.gitlab.arturbosch.detekt.api.Config
 import io.gitlab.arturbosch.detekt.sample.extensions.rules.TooManyFunctions
 import io.gitlab.arturbosch.detekt.test.lint
 import org.assertj.core.api.Assertions.assertThat
@@ -8,7 +9,7 @@ import org.spekframework.spek2.style.specification.describe
 
 class TooManyFunctionsSpec : Spek({
 
-    val subject by memoized { TooManyFunctions() }
+    val subject by memoized { TooManyFunctions(Config.empty) }
 
     describe("a simple test") {
 

docs/pages/extensions.md

@@ -21,12 +21,12 @@ The easiest way to define a rule set is to clone the provided **detekt-sample-ex
 
 Own rules have to extend the abstract _Rule_ class and override the `visitXXX()`-functions from the AST.  
 A `RuleSetProvider` must be implemented, which declares a `RuleSet` in the `instance()`-function.
-To allow your rule to be configurable, pass it a Config object from within your rule set provider.  
+To leverage the configuration mechanism of detekt you must pass the Config object from your rule set provider to your rule.
 An `Issue` property defines what ID, severity and message should be printed on the console or on any other output format.
 
 Example of a custom rule:
 ```kotlin
-class TooManyFunctions : Rule() {
+class TooManyFunctions(config: Config) : Rule(config) {
 
     override val issue = Issue(javaClass.simpleName,
         Severity.CodeSmell,
@@ -87,11 +87,14 @@ class TooManyFunctions2(config: Config) : ThresholdRule(config, THRESHOLD) {
 }
 ```
 
-If you want your rule to be configurable, write down your properties inside the detekt.yml file:
+If you want your rule to be configurable, write down your properties inside the detekt.yml file.
+Please note that this will only take effect, if the `Config` object is passed on by the `RuleSetProvider`
+to the rule itself.
 
 ```yaml
 MyRuleSet:
   TooManyFunctions2:
+    active: true
     threshold: 10
   OtherRule:
     active: false
@@ -223,9 +226,9 @@ dependencies {
 
 ##### Pitfalls
 
-- By default all rules not annotated with `@ActiveByDefault` are disabled.
-That means your custom rules are also disabled if you have not explicitly enabled
-them in the `detekt` yaml configuration file.
+- All rules are disabled by default and have to be explicitly enabled in the `detekt` yaml configuration file.
+- If you do not pass the `Config` object from the `RuleSetProvider` to the rule, the rule is active, but you will not be able to use
+any configuration options or disable the rule via config file.
 - If your extension is part of your project and you integrate it like `detektPlugins project(":my-rules")` make sure that this
 subproject is build before `gradle detekt` is run.
 In the `kotlin-dsl` you could add something like `tasks.withType<Detekt> { dependsOn(":my-rules:assemble") }` to explicitly run `detekt` only