Update changelog and cleanup

Closes pinterest#631

CHANGELOG.md

@@ -4,11 +4,29 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 
 ## Unreleased
 
+### API Changes & RuleSet providers
+
+If you are not an API user nor a RuleSet provider, then you can safely skip this section. Otherwise, please read below carefully and upgrade your usage of ktlint. In this and coming releases, we are changing and adapting important parts of our API in order to increase maintainability and flexibility for future changes. Please avoid skipping a releases as that will make it harder to migrate.
+
+#### Rule lifecycle hooks / deprecate RunOnRootOnly visitor modifier
+
+Up until ktlint 0.46 the Rule class provided only one life cycle hook. This "visit" hook was called in a depth-first-approach on all nodes in the file. A rule like the IndentationRule used the RunOnRootOnly visitor modifier to call this lifecycle hook for the root node only in combination with an alternative way of traversing the ASTNodes. Downside of this approach was that suppression of the rule on blocks inside a file was not possible ([#631](https://github.com/pinterest/ktlint/issues/631)). More generically, this applied to all rules, applying alternative traversals of the AST.
+
+The Rule class now offers new life cycle hooks:
+* beforeFirstNode: This method is called once before the first node is visited. It can be used to initialize the state of the rule before processing of nodes starts. The ".editorconfig" properties (including overrides) are provided as parameter.
+* beforeVisitChildNodes: This method is called on a node in AST before visiting its child nodes. This is repeated recursively for the child nodes resulting in a depth first traversal of the AST. This method is the equivalent of the "visit" life cycle hooks. However, note that in KtLint 0.48, the UserData of the rootnode no longer provides access to the ".editorconfig" properties. This method can be used to emit Lint Violations and to autocorrect if applicable.
+* afterVisitChildNodes: This method is called on a node in AST after all its child nodes have been visited. This method can be used to emit Lint Violations and to autocorrect if applicable.
+* afterLastNode: This method is called once after the last node in the AST is visited. It can be used for teardown of the state of the rule.
+
+The "visit" life cycle hook will be removed in Ktlint 0.48. In KtLint 0.47 the "visit" life cycle hook will be called *only* when hook "beforeVisitChildNodes" is not overridden. It is recommended to migrate to the new lifecycle hooks in KtLint 0.47. Please create an issue, in case you need additional assistence to implement the new life cycle hooks in your rules.
+
+
 ### Added
 
 ### Fixed
 
 * Fix cli argument "--disabled_rules" ([#1520](https://github.com/pinterest/ktlint/issue/1520)).
+* Disable/enable IndentationRule on blocks in middle of file. (`indent`) [#631](https://github.com/pinterest/ktlint/issues/631)
 
 ### Changed
 

ktlint-core/src/main/kotlin/com/pinterest/ktlint/core/Rule.kt

@@ -52,8 +52,10 @@ public open class Rule(
         visit(node, autoCorrect, emit)
 
     /**
-     * For backwards compatibility reasons, this method is called by default implementation of [beforeVisitChildNodes].
-     * Existing implementations of the [visit] method should be renamed tp [beforeVisitChildNodes].
+     * Rules that override method [visit] should rename that method to [beforeVisitChildNodes]. For backwards
+     * compatibility reasons (in KtLint 0.47 only), this method is called via the default implementation of
+     * [beforeVisitChildNodes]. Whenever [beforeVisitChildNodes] is overridden with a custom implementation, this method
+     * will no longer be called.
      *
      * @param node AST node
      * @param autoCorrect indicates whether rule should attempt auto-correction

ktlint-core/src/test/kotlin/com/pinterest/ktlint/core/KtLintTest.kt

@@ -657,7 +657,7 @@ private class SimpleTestRuleLegacy(
     id: String,
     visitorModifiers: Set<VisitorModifier> = emptySet()
 ) : Rule(id, visitorModifiers) {
-    override fun beforeVisitChildNodes(
+    override fun visit(
         node: ASTNode,
         autoCorrect: Boolean,
         emit: (offset: Int, errorMessage: String, canBeAutoCorrected: Boolean) -> Unit

ktlint/src/main/kotlin/com/pinterest/ktlint/internal/FileUtils.kt

@@ -187,9 +187,6 @@ internal fun lintFile(
     )
 )
 
-/**
- * Format a kotlin file or script file
- */
 /**
  * Format a kotlin file or script file
  */