SONAR-1901: Add new rule to report on "Undocumented API"

7 files changed, 61 insertions, 93 deletions

diff --git a/plugins/sonar-squid-java-plugin/src/main/java/org/sonar/java/ast/JavaAstScanner.java b/plugins/sonar-squid-java-plugin/src/main/java/org/sonar/java/ast/JavaAstScanner.java
index 290fbc80805..5a5094dae57 100644
--- a/plugins/sonar-squid-java-plugin/src/main/java/org/sonar/java/ast/JavaAstScanner.java
+++ b/plugins/sonar-squid-java-plugin/src/main/java/org/sonar/java/ast/JavaAstScanner.java
@@ -19,40 +19,16 @@
  */
 package org.sonar.java.ast;
 
-import java.io.ByteArrayInputStream;
-import java.io.File;
-import java.io.InputStream;
-import java.nio.charset.Charset;
-import java.util.ArrayList;
-import java.util.Arrays;
-import java.util.Collection;
-import java.util.List;
-import java.util.Stack;
-
 import org.apache.commons.io.FileUtils;
 import org.apache.commons.io.IOUtils;
 import org.apache.commons.io.filefilter.FileFilterUtils;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
-import org.sonar.java.ast.visitor.AccessorVisitor;
-import org.sonar.java.ast.visitor.AnonymousInnerClassVisitor;
-import org.sonar.java.ast.visitor.BlankLinesVisitor;
-import org.sonar.java.ast.visitor.BranchVisitor;
-import org.sonar.java.ast.visitor.ClassVisitor;
-import org.sonar.java.ast.visitor.CommentVisitor;
-import org.sonar.java.ast.visitor.ComplexityVisitor;
-import org.sonar.java.ast.visitor.EndAtLineVisitor;
-import org.sonar.java.ast.visitor.FileVisitor;
-import org.sonar.java.ast.visitor.JavaAstVisitor;
-import org.sonar.java.ast.visitor.LinesOfCodeVisitor;
-import org.sonar.java.ast.visitor.LinesVisitor;
-import org.sonar.java.ast.visitor.MethodVisitor;
-import org.sonar.java.ast.visitor.PackageVisitor;
-import org.sonar.java.ast.visitor.PublicApiVisitor;
-import org.sonar.java.ast.visitor.StatementVisitor;
+import org.sonar.java.ast.visitor.*;
 import org.sonar.java.squid.JavaSquidConfiguration;
 import org.sonar.squid.api.AnalysisException;
 import org.sonar.squid.api.CodeScanner;
+import org.sonar.squid.api.CodeVisitor;
 import org.sonar.squid.api.SourceCode;
 import org.xml.sax.InputSource;
 
@@ -61,6 +37,12 @@ import com.puppycrawl.tools.checkstyle.ConfigurationLoader;
 import com.puppycrawl.tools.checkstyle.PropertiesExpander;
 import com.puppycrawl.tools.checkstyle.api.Configuration;
 
+import java.io.ByteArrayInputStream;
+import java.io.File;
+import java.io.InputStream;
+import java.nio.charset.Charset;
+import java.util.*;
+
 /**
  * Squid uses Checkstyle to get an out-of-the-box java parser with AST generation and visitor pattern support.
  */
@@ -179,4 +161,11 @@ public class JavaAstScanner extends CodeScanner<JavaAstVisitor> {
     visitorClasses.add(LinesOfCodeVisitor.class);
     return visitorClasses;
   }
+
+  @Override
+  public void accept(CodeVisitor visitor) {
+    if (visitor instanceof JavaAstVisitor) {
+      super.accept(visitor);
+    }
+  }
 }
diff --git a/plugins/sonar-squid-java-plugin/src/main/java/org/sonar/java/ast/visitor/PublicApiVisitor.java b/plugins/sonar-squid-java-plugin/src/main/java/org/sonar/java/ast/visitor/PublicApiVisitor.java
index 896b9260482..92e3fd25112 100644
--- a/plugins/sonar-squid-java-plugin/src/main/java/org/sonar/java/ast/visitor/PublicApiVisitor.java
+++ b/plugins/sonar-squid-java-plugin/src/main/java/org/sonar/java/ast/visitor/PublicApiVisitor.java
@@ -19,9 +19,6 @@
  */
 package org.sonar.java.ast.visitor;
 
-import java.util.Arrays;
-import java.util.List;
-
 import org.sonar.squid.api.SourceCode;
 import org.sonar.squid.measures.Metric;
 
@@ -31,6 +28,9 @@ import com.puppycrawl.tools.checkstyle.api.DetailAST;
 import com.puppycrawl.tools.checkstyle.api.Scope;
 import com.puppycrawl.tools.checkstyle.api.TokenTypes;
 
+import java.util.Arrays;
+import java.util.List;
+
 public class PublicApiVisitor extends JavaAstVisitor {
 
   final static String OVERRIDE_ANNOTATION_KEYWORD = "Override";
@@ -49,7 +49,7 @@ public class PublicApiVisitor extends JavaAstVisitor {
   @Override
   public void visitToken(DetailAST ast) {
     SourceCode currentResource = peekSourceCode();
-    if (isPublic(ast) && !isStaticFinalVariable(ast) && !isMethodWithOverrideAnnotation(ast) && !isEmptyDefaultConstructor(ast)) {
+    if (isPublicApi(ast)) {
       currentResource.add(Metric.PUBLIC_API, 1);
       if (isDocumentedApi(ast)) {
         currentResource.add(Metric.PUBLIC_DOC_API, 1);
@@ -57,6 +57,10 @@ public class PublicApiVisitor extends JavaAstVisitor {
     }
   }
 
+  protected boolean isPublicApi(DetailAST ast) {
+    return isPublic(ast) && !isStaticFinalVariable(ast) && !isMethodWithOverrideAnnotation(ast) && !isEmptyDefaultConstructor(ast);
+  }
+
   private boolean isEmptyDefaultConstructor(DetailAST ast) {
     return (isConstructorWithoutParameters(ast)) && (ast.getLastChild().getChildCount() == 1);
   }
@@ -90,7 +94,7 @@ public class PublicApiVisitor extends JavaAstVisitor {
     return (AstUtils.isScope(AstUtils.getScope(ast), Scope.PUBLIC) || AstUtils.isType(ast, TokenTypes.ANNOTATION_FIELD_DEF));
   }
 
-  private boolean isDocumentedApi(DetailAST ast) {
+  protected boolean isDocumentedApi(DetailAST ast) {
     return getFileContents().getJavadocBefore(ast.getLineNo()) != null;
   }
 
diff --git a/plugins/sonar-squid-java-plugin/src/main/java/org/sonar/java/bytecode/BytecodeScanner.java b/plugins/sonar-squid-java-plugin/src/main/java/org/sonar/java/bytecode/BytecodeScanner.java
index b3716013c90..fde4fddf9b6 100644
--- a/plugins/sonar-squid-java-plugin/src/main/java/org/sonar/java/bytecode/BytecodeScanner.java
+++ b/plugins/sonar-squid-java-plugin/src/main/java/org/sonar/java/bytecode/BytecodeScanner.java
@@ -19,30 +19,22 @@
  */
 package org.sonar.java.bytecode;
 
-import java.io.File;
-import java.util.ArrayList;
-import java.util.Arrays;
-import java.util.Collection;
-import java.util.List;
-
-import org.sonar.java.bytecode.asm.AsmClass;
-import org.sonar.java.bytecode.asm.AsmClassProvider;
-import org.sonar.java.bytecode.asm.AsmClassProviderImpl;
-import org.sonar.java.bytecode.asm.AsmMethod;
+import org.sonar.java.bytecode.asm.*;
 import org.sonar.java.bytecode.asm.AsmClassProvider.DETAIL_LEVEL;
-import org.sonar.java.bytecode.visitor.AccessorVisitor;
-import org.sonar.java.bytecode.visitor.BytecodeVisitor;
-import org.sonar.java.bytecode.visitor.DITVisitor;
-import org.sonar.java.bytecode.visitor.DependenciesVisitor;
-import org.sonar.java.bytecode.visitor.LCOM4Visitor;
-import org.sonar.java.bytecode.visitor.NOCVisitor;
-import org.sonar.java.bytecode.visitor.RFCVisitor;
+import org.sonar.java.bytecode.visitor.*;
 import org.sonar.squid.api.CodeScanner;
+import org.sonar.squid.api.CodeVisitor;
 import org.sonar.squid.api.SourceClass;
 import org.sonar.squid.api.SourceCode;
 import org.sonar.squid.indexer.QueryByType;
 import org.sonar.squid.indexer.SquidIndex;
 
+import java.io.File;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Collection;
+import java.util.List;
+
 public class BytecodeScanner extends CodeScanner<BytecodeVisitor> {
 
   private SquidIndex indexer;
@@ -103,4 +95,11 @@ public class BytecodeScanner extends CodeScanner<BytecodeVisitor> {
     visitorClasses.add(DependenciesVisitor.class);
     return visitorClasses;
   }
+
+  @Override
+  public void accept(CodeVisitor visitor) {
+    if (visitor instanceof BytecodeVisitor) {
+      super.accept(visitor);
+    }
+  }
 }
diff --git a/plugins/sonar-squid-java-plugin/src/main/java/org/sonar/java/bytecode/check/BytecodeChecks.java b/plugins/sonar-squid-java-plugin/src/main/java/org/sonar/java/bytecode/check/BytecodeChecks.java
deleted file mode 100644
index 96b921f9769..00000000000
--- a/plugins/sonar-squid-java-plugin/src/main/java/org/sonar/java/bytecode/check/BytecodeChecks.java
+++ /dev/null
@@ -1,37 +0,0 @@
-/*
- * Sonar, open source software quality management tool.
- * Copyright (C) 2009 SonarSource SA
- * mailto:contact AT sonarsource DOT com
- *
- * Sonar is free software; you can redistribute it and/or
- * modify it under the terms of the GNU Lesser General Public
- * License as published by the Free Software Foundation; either
- * version 3 of the License, or (at your option) any later version.
- *
- * Sonar is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
- * Lesser General Public License for more details.
- *
- * You should have received a copy of the GNU Lesser General Public
- * License along with Sonar; if not, write to the Free Software
- * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02
- */
-package org.sonar.java.bytecode.check;
-
-import java.util.Arrays;
-import java.util.List;
-
-public final class BytecodeChecks {
-
-  private BytecodeChecks() {
-  }
-
-  public static List<Class> getCheckClasses() {
-    return Arrays.asList(
-        (Class) CallToDeprecatedMethodCheck.class,
-        UnusedPrivateMethodCheck.class,
-        UnusedProtectedMethodCheck.class, 
-        ArchitectureCheck.class);
-  }
-}
diff --git a/plugins/sonar-squid-java-plugin/src/main/java/org/sonar/plugins/squid/SquidExecutor.java b/plugins/sonar-squid-java-plugin/src/main/java/org/sonar/plugins/squid/SquidExecutor.java
index d151511bb9f..bab76dee513 100644
--- a/plugins/sonar-squid-java-plugin/src/main/java/org/sonar/plugins/squid/SquidExecutor.java
+++ b/plugins/sonar-squid-java-plugin/src/main/java/org/sonar/plugins/squid/SquidExecutor.java
@@ -28,12 +28,12 @@ import org.sonar.api.resources.Resource;
 import org.sonar.api.utils.TimeProfiler;
 import org.sonar.java.ast.JavaAstScanner;
 import org.sonar.java.bytecode.BytecodeScanner;
-import org.sonar.java.bytecode.check.BytecodeCheck;
 import org.sonar.java.squid.JavaSquidConfiguration;
 import org.sonar.plugins.squid.bridges.Bridge;
 import org.sonar.plugins.squid.bridges.BridgeFactory;
 import org.sonar.plugins.squid.bridges.ResourceIndex;
 import org.sonar.squid.Squid;
+import org.sonar.squid.api.CodeVisitor;
 import org.sonar.squid.api.SourceCode;
 import org.sonar.squid.api.SourceFile;
 import org.sonar.squid.api.SourcePackage;
@@ -79,11 +79,11 @@ public final class SquidExecutor {
   }
 
   public void scan(Collection<File> sourceFiles, Collection<File> bytecodeFilesOrDirectories) {
+    for (Object checker : checkFactory.getChecks()) {
+      squid.registerVisitor((CodeVisitor) checker);
+    }
     scanSources(sourceFiles);
     if (sourceScanned) {
-      for (Object checker : checkFactory.getChecks()) {
-        squid.registerVisitor((BytecodeCheck) checker);
-      }
       scanBytecode(bytecodeFilesOrDirectories);
     }
     squid.decorateSourceCodeTreeWith(Metric.values());
diff --git a/plugins/sonar-squid-java-plugin/src/main/java/org/sonar/plugins/squid/SquidRuleRepository.java b/plugins/sonar-squid-java-plugin/src/main/java/org/sonar/plugins/squid/SquidRuleRepository.java
index e4af4723946..74078394435 100644
--- a/plugins/sonar-squid-java-plugin/src/main/java/org/sonar/plugins/squid/SquidRuleRepository.java
+++ b/plugins/sonar-squid-java-plugin/src/main/java/org/sonar/plugins/squid/SquidRuleRepository.java
@@ -4,8 +4,13 @@ import org.sonar.api.resources.Java;
 import org.sonar.api.rules.AnnotationRuleParser;
 import org.sonar.api.rules.Rule;
 import org.sonar.api.rules.RuleRepository;
-import org.sonar.java.bytecode.check.BytecodeChecks;
+import org.sonar.java.ast.check.UndocumentedApiCheck;
+import org.sonar.java.bytecode.check.ArchitectureCheck;
+import org.sonar.java.bytecode.check.CallToDeprecatedMethodCheck;
+import org.sonar.java.bytecode.check.UnusedPrivateMethodCheck;
+import org.sonar.java.bytecode.check.UnusedProtectedMethodCheck;
 
+import java.util.Arrays;
 import java.util.List;
 
 public final class SquidRuleRepository extends RuleRepository {
@@ -19,6 +24,15 @@ public final class SquidRuleRepository extends RuleRepository {
 
   @Override
   public List<Rule> createRules() {
-    return ruleParser.parse(SquidConstants.REPOSITORY_KEY, BytecodeChecks.getCheckClasses());
+    return ruleParser.parse(SquidConstants.REPOSITORY_KEY, getCheckClasses());
+  }
+
+  public static List<Class> getCheckClasses() {
+    return Arrays.asList(
+        (Class) CallToDeprecatedMethodCheck.class,
+        UnusedPrivateMethodCheck.class,
+        UnusedProtectedMethodCheck.class,
+        ArchitectureCheck.class,
+        UndocumentedApiCheck.class);
   }
 }
diff --git a/plugins/sonar-squid-java-plugin/src/main/java/org/sonar/plugins/squid/SquidSensor.java b/plugins/sonar-squid-java-plugin/src/main/java/org/sonar/plugins/squid/SquidSensor.java
index 4804d306d4a..e2f58dca855 100644
--- a/plugins/sonar-squid-java-plugin/src/main/java/org/sonar/plugins/squid/SquidSensor.java
+++ b/plugins/sonar-squid-java-plugin/src/main/java/org/sonar/plugins/squid/SquidSensor.java
@@ -36,7 +36,6 @@ import org.sonar.api.profiles.RulesProfile;
 import org.sonar.api.resources.Java;
 import org.sonar.api.resources.Project;
 import org.sonar.api.utils.SonarException;
-import org.sonar.java.bytecode.check.BytecodeChecks;
 
 import java.io.File;
 import java.nio.charset.Charset;
@@ -73,7 +72,7 @@ public class SquidSensor implements Sensor {
         SquidPluginProperties.FIELDS_TO_EXCLUDE_FROM_LCOM4_COMPUTATION_DEFAULT_VALUE);
     Charset charset = project.getFileSystem().getSourceCharset();
 
-    AnnotationCheckFactory factory = AnnotationCheckFactory.create(profile, SquidConstants.REPOSITORY_KEY, BytecodeChecks.getCheckClasses());
+    AnnotationCheckFactory factory = AnnotationCheckFactory.create(profile, SquidConstants.REPOSITORY_KEY, SquidRuleRepository.getCheckClasses());
 
     SquidExecutor squidExecutor = new SquidExecutor(analyzePropertyAccessors, fieldNamesToExcludeFromLcom4Computation, factory, charset);
     squidExecutor.scan(getSourceFiles(project), getBytecodeFiles(project));