Replace assert with Logger#assertTrue in InspectionEngine + javadoc improvements

platform/analysis-api/src/com/intellij/codeInspection/LocalInspectionTool.java

@@ -110,7 +110,7 @@ public abstract class LocalInspectionTool extends InspectionProfileEntry {
   /**
    * Override the method to provide your own inspection visitor, if you need to store additional state in the
    * LocalInspectionToolSession user data or get information about the inspection scope.
-   * Visitor created must not be recursive (it must not inherit {@link PsiRecursiveVisitor})
+   * Created visitor must not be recursive (e.g. it must not inherit {@link PsiRecursiveElementVisitor})
    * since it will be fed with every element in the file anyway.
    * Visitor created must be thread-safe since it might be called on several elements concurrently.
    *
@@ -118,6 +118,7 @@ public abstract class LocalInspectionTool extends InspectionProfileEntry {
    * @param isOnTheFly true if inspection was run in non-batch mode
    * @param session    the session in the context of which the tool runs.
    * @return not-null visitor for this inspection.
+   * @see PsiRecursiveVisitor
    */
   @NotNull
   public PsiElementVisitor buildVisitor(@NotNull final ProblemsHolder holder, final boolean isOnTheFly, @NotNull LocalInspectionToolSession session) {
@@ -126,13 +127,14 @@ public abstract class LocalInspectionTool extends InspectionProfileEntry {
 
   /**
    * Override the method to provide your own inspection visitor.
-   * Visitor created must not be recursive (it must not inherit {@link PsiRecursiveVisitor})
+   * Created visitor must not be recursive (e.g. it must not inherit {@link PsiRecursiveElementVisitor})
    * since it will be fed with every element in the file anyway.
    * Visitor created must be thread-safe since it might be called on several elements concurrently.
    *
    * @param holder     where visitor will register problems found.
    * @param isOnTheFly true if inspection was run in non-batch mode
    * @return not-null visitor for this inspection.
+   * @see PsiRecursiveVisitor
    */
   @NotNull
   public PsiElementVisitor buildVisitor(@NotNull final ProblemsHolder holder, final boolean isOnTheFly) {

platform/analysis-impl/src/com/intellij/codeInspection/InspectionEngine.java

@@ -63,8 +63,8 @@ public class InspectionEngine {
     if(visitor == null) {
       LOG.error("Tool " + tool + " (" + tool.getClass()+ ") must not return null from the buildVisitor() method");
     }
-    assert !(visitor instanceof PsiRecursiveVisitor)
-      : "The visitor returned from LocalInspectionTool.buildVisitor() must not be recursive: " + tool;
+    LOG.assertTrue(!(visitor instanceof PsiRecursiveVisitor),
+                   "The visitor returned from LocalInspectionTool.buildVisitor() must not be recursive: " + tool);
 
     tool.inspectionStarted(session, isOnTheFly);
     acceptElements(elements, visitor, elementDialectIds, dialectIdsSpecifiedForTool);

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

@@ -2,7 +2,10 @@
 package com.intellij.psi;
 
 /**
- * Marker interface for recursive PSI visitors.
+ * Please use this interface to mark recursive visitors.
+ * This information can then be used by the runtime to find accidental performance issues, e.g. see assertions in
+ * com.intellij.codeInspection.LocalInspectionTool#processFile and
+ * com.intellij.codeInspection.InspectionEngine#createVisitorAndAcceptElements.
  */
 public interface PsiRecursiveVisitor {
 }