PY-20537: Invalidate caches in "clearCaches", not "subtreeChanged"

"clearCaches" is the right place to invalidate caches because
"subtreeChanged" is not always called: some times only "onContentChanged"
called. Both methods call "clearCaches" though.

"clearCaches" moved to interface level since it is part of public API now

platform/core-api/src/com/intellij/psi/PsiFile.java

@@ -101,8 +101,18 @@ public interface PsiFile extends PsiFileSystemItem {
   FileASTNode getNode();
 
   /**
-   * Called by the PSI framework when the contents of the file changes. Can be used to invalidate
-   * file-level caches. If you override this method, you <b>must</b> call the base class implementation.
+   * Called by the PSI framework when the contents of the file changes.
+   * If you override this method, you <b>must</b> call the base class implementation.
+   * While this method can be used to invalidate file-level caches, it is more much safe to invalidate them in  {@link #clearCaches()}
+   * since file contents can be reloaded completely (without any specific subtree change) without this method being called.
    */
   void subtreeChanged();
+
+  /**
+   * Invalidate any file-specific cache in this method. It is called on file file content change.
+   * If you override this method, you <b>must</b> call the base class implementation.
+   */
+  default void clearCaches() {
+
+  }
 }

platform/core-impl/src/com/intellij/psi/impl/source/PsiFileImpl.java

@@ -368,6 +368,7 @@ public abstract class PsiFileImpl extends ElementBase implements PsiFileEx, PsiF
     return treeElement;
   }
 
+  @Override
   public void clearCaches() {
     myModificationStamp ++;
   }

python/src/com/jetbrains/python/psi/impl/PyFileImpl.java

@@ -729,8 +729,8 @@ public class PyFileImpl extends PsiFileBase implements PyFile, PyExpression {
   }
 
   @Override
-  public void subtreeChanged() {
-    super.subtreeChanged();
+  public void clearCaches() {
+    super.clearCaches();
     ControlFlowCache.clear(this);
     myDunderAllCalculated = false;
     myFutureFeatures.clear(); // probably no need to synchronize