Add Public API metrics and violations

cxx-checks/src/main/java/org/sonar/cxx/checks/CheckList.java

@@ -60,6 +60,7 @@ public static List<Class> getChecks() {
         TooLongLineCheck.class,
         TooManyLinesOfCodeInFileCheck.class,
         TooManyStatementsPerLineCheck.class,
+        UndocumentedApiCheck.class,
         UnnamedNamespaceInHeaderCheck.class,
         UselessParenthesesCheck.class,
         UseCorrectTypeCheck.class,

cxx-checks/src/main/java/org/sonar/cxx/checks/UndocumentedApiCheck.java

@@ -0,0 +1,92 @@
+/*
+ * Sonar C++ Plugin (Community)
+ * Copyright (C) 2011 Waleri Enns and CONTACT Software GmbH
+ * dev@sonar.codehaus.org
+ *
+ * This program 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.
+ *
+ * This program 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 this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02
+ */
+package org.sonar.cxx.checks;
+
+import java.util.Arrays;
+import java.util.List;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.sonar.check.Priority;
+import org.sonar.check.Rule;
+import org.sonar.cxx.visitors.AbstractCxxPublicApiVisitor;
+
+import com.sonar.sslr.api.AstNode;
+import com.sonar.sslr.api.Grammar;
+import com.sonar.sslr.api.Token;
+
+/**
+ * Check that generates issue for undocumented API items.<br>
+ * Following items are counted as public API:
+ * <ul>
+ * <li>classes/structures</li>
+ * <li>class members (public and protected)</li>
+ * <li>structure members</li>
+ * <li>enumerations</li>
+ * <li>enumeration values</li>
+ * <li>typedefs</li>
+ * <li>functions</li>
+ * <li>variables</li>
+ * </ul>
+ * <p>
+ * Public API items are considered documented if they have Doxygen comments.<br>
+ * Function arguments are not counted since they can be documented in function
+ * documentation and this visitor does not parse Doxygen comments.<br>
+ * This visitor should be applied only on header files.<br>
+ * Currently, no filtering is applied using preprocessing directive.<br>
+ * <p>
+ * Limitation: only "in front of the declaration" comments are considered.
+ *
+ * @see <a href="http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html">
+ *      Doxygen Manual: Documenting the code</a>
+ *
+ * @author Ludovic Cintrat
+ *
+ * @param <GRAMMAR>
+ */
+@Rule(key = "UndocumentedApi",
+      description = "All public APIs should be documented",
+      priority = Priority.MINOR)
+public class UndocumentedApiCheck extends AbstractCxxPublicApiVisitor<Grammar> {
+
+    private static final Logger LOG = LoggerFactory
+            .getLogger("UndocumentedApiCheck");
+
+    private static final List<String> DEFAULT_NAME_SUFFIX = Arrays.asList(".h",
+            ".hh", ".hpp", ".H");
+
+    public UndocumentedApiCheck() {
+        super();
+        withHeaderFileSuffixes(DEFAULT_NAME_SUFFIX);
+    }
+
+    @Override
+    protected void onPublicApi(AstNode node, String id, List<Token> comments) {
+        boolean commented = !comments.isEmpty();
+
+        LOG.debug("node: " + node.getType() + " line: " + node.getTokenLine()
+                + " id: '" + id + "' documented: " + commented);
+
+        if (!commented) {
+            getContext().createLineViolation(this, "Undocumented API: " + id,
+                    node);
+        }
+    }
+}

cxx-checks/src/main/resources/org/sonar/l10n/cxx.properties

@@ -44,6 +44,7 @@ rule.cxx.TooManyLinesOfCodeInFile.param.max=Maximum code lines allowed.
 rule.cxx.TooManyStatementsPerLine.name=Statements should be on separate lines
 rule.cxx.TooManyStatementsPerLine.param.excludeCaseBreak=Exclude 'break' statement if it is on the same line as the switch label (case: or default:).
 rule.cxx.UnnamedNamespaceInHeader.name=Unnamed namespaces are not allowed in header files
+rule.cxx.UndocumentedApi.name=Public APIs should be documented
 rule.cxx.UseCorrectType.name=C++ type(s) shall be used 
 rule.cxx.UseCorrectType.param.message=Use C++ types whenever possible
 rule.cxx.UseCorrectType.param.regularExpression=Type regular expression rule

cxx-checks/src/main/resources/org/sonar/l10n/cxx/rules/cxx/UndocumentedApi.html

@@ -0,0 +1,24 @@
+<p>
+Public APIs have to be documented in order to be used by customers.<br>
+APIs documentation is typically generated using a tool, such as <a href="http://www.stack.nl/~dimitri/doxygen/index.html">Doxygen</a>.
+</p>
+
+<p>The following code illustrates a well documented class:</p>
+
+<pre>
+/**
+  class documentation
+/*
+class DocumentedClass {
+  public:
+    int commentedVar; ///< documentation
+
+    /**
+      apiMethod documentation
+     */
+    void apiMethod();
+
+  private:
+    void notInApiMethod();
+};
+</pre>

cxx-checks/src/test/java/org/sonar/cxx/checks/CheckListTest.java

@@ -27,6 +27,6 @@ public class CheckListTest {
 
   @Test
   public void count() {
-    assertThat(CheckList.getChecks().size()).isEqualTo(33);
+    assertThat(CheckList.getChecks().size()).isEqualTo(34);
   }
 }

cxx-checks/src/test/java/org/sonar/cxx/checks/UndocumentedApiCheckTest.java

@@ -0,0 +1,57 @@
+/*
+ * Sonar C++ Plugin (Community)
+ * Copyright (C) 2011 Waleri Enns and CONTACT Software GmbH
+ * dev@sonar.codehaus.org
+ *
+ * This program 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.
+ *
+ * This program 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 this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02
+ */
+package org.sonar.cxx.checks;
+
+import java.io.File;
+
+import org.junit.Rule;
+import org.junit.Test;
+import org.sonar.cxx.CxxAstScanner;
+import org.sonar.squid.api.CheckMessage;
+import org.sonar.squid.api.SourceFile;
+
+import static org.fest.assertions.Assertions.assertThat;
+
+import com.sonar.sslr.squid.checks.CheckMessagesVerifierRule;
+
+public class UndocumentedApiCheckTest {
+
+    @Rule
+    public CheckMessagesVerifierRule checkMessagesVerifier = new CheckMessagesVerifierRule();
+
+    @SuppressWarnings("unchecked")
+    @Test
+    public void detected() {
+        SourceFile file = CxxAstScanner.scanSingleFile(new File(
+                "src/test/resources/checks/UndocumentedApiCheck/no_doc.h"), new UndocumentedApiCheck());
+
+        checkMessagesVerifier.verify(file.getCheckMessages()).next().atLine(6)
+                .next().atLine(11).next().atLine(13).next().atLine(14).next()
+                .atLine(17).next().atLine(19).next().atLine(21).next()
+                .atLine(23).next().atLine(26).next().atLine(48).next()
+                .atLine(52).next().atLine(53).next().atLine(56).next()
+                .atLine(58).next().atLine(60).next().atLine(63).next()
+                .atLine(65).next().atLine(68).next().atLine(74).next().atLine(77);
+
+        for (CheckMessage msg : file.getCheckMessages()) {
+            assertThat(msg.formatDefaultMessage()).isNotEmpty();
+        }
+    }
+}

cxx-checks/src/test/resources/checks/UndocumentedApiCheck/no_doc.h

@@ -0,0 +1,79 @@
+#define TEST_MACRO() \
+	macro
+
+#define EXPORT
+
+class testClass
+{
+	void defaultMethod();
+
+public:
+	void publicMethod();
+
+	enum classEnum {
+		classEnumValue
+	}
+
+	enumVar;
+
+	EXPORT int publicAttribute;
+
+	int inlineCommentedAttr; 
+
+	void inlinePublicMethod();
+
+protected:
+	virtual void protectedMethod();
+
+private:
+	void privateMethod();
+
+	enum privateEnum {
+		privateEnumVal
+	};
+
+	struct privateStruct {
+		int privateStructField;
+	};
+
+	class privateClass {
+		int i;
+	};
+
+	union privateUnion {
+		int u;
+	};
+
+public:
+	int inlineCommentedLastAttr;
+};
+
+
+struct testStruct {
+    int testField;
+};
+
+extern int globalVar; 
+
+void testFunction();
+
+enum emptyEnum
+{};
+
+enum testEnum
+{
+  enum_val
+};
+
+union testUnion
+{
+
+};
+
+template<T>
+struct tmplStruct
+{};
+
+void func() {
+  for (int i = 0; i < 10; i++) {}
+}

cxx-squid/src/main/java/org/sonar/cxx/CxxAstScanner.java

@@ -25,7 +25,6 @@
 import com.sonar.sslr.api.Token;
 import com.sonar.sslr.impl.Parser;
 import com.sonar.sslr.api.Grammar;
-
 import com.sonar.sslr.squid.AstScanner;
 import com.sonar.sslr.squid.SourceCodeBuilderCallback;
 import com.sonar.sslr.squid.SourceCodeBuilderVisitor;
@@ -35,6 +34,7 @@
 import com.sonar.sslr.squid.metrics.ComplexityVisitor;
 import com.sonar.sslr.squid.metrics.CounterVisitor;
 import com.sonar.sslr.squid.metrics.LinesVisitor;
+
 import org.sonar.cxx.api.CxxKeyword;
 import org.sonar.cxx.api.CxxMetric;
 import org.sonar.cxx.api.CxxPunctuator;
@@ -44,6 +44,7 @@
 import org.sonar.cxx.visitors.CxxFileVisitor;
 import org.sonar.cxx.visitors.CxxLinesOfCodeVisitor;
 import org.sonar.cxx.visitors.CxxParseErrorLoggerVisitor;
+import org.sonar.cxx.visitors.CxxPublicApiVisitor;
 import org.sonar.squid.api.SourceClass;
 import org.sonar.squid.api.SourceCode;
 import org.sonar.squid.api.SourceFile;
@@ -153,6 +154,9 @@ public SourceCode createSourceCode(SourceCode parentSourceCode, AstNode astNode)
     /* Metrics */
     builder.withSquidAstVisitor(new LinesVisitor<Grammar>(CxxMetric.LINES));
     builder.withSquidAstVisitor(new CxxLinesOfCodeVisitor<Grammar>(CxxMetric.LINES_OF_CODE));
+    builder.withSquidAstVisitor(new CxxPublicApiVisitor<Grammar>(CxxMetric.PUBLIC_API,
+                                                                 CxxMetric.PUBLIC_UNDOCUMENTED_API)
+        .withHeaderFileSuffixes(conf.getHeaderFileSuffixes()));
 
     builder.withSquidAstVisitor(CommentsVisitor.<Grammar> builder().withCommentMetric(CxxMetric.COMMENT_LINES)
         .withNoSonar(true)

cxx-squid/src/main/java/org/sonar/cxx/CxxConfiguration.java

@@ -32,6 +32,7 @@ public class CxxConfiguration extends SquidConfiguration {
   private List<String> defines = new ArrayList<String>();
   private List<String> includeDirectories = new ArrayList<String>();
   private List<String> forceIncludeFiles = new ArrayList<String>();
+  private List<String> headerFileSuffixes = new ArrayList<String>();
   private String baseDir;
   private boolean errorRecoveryEnabled = true;
 
@@ -107,4 +108,18 @@ public void setErrorRecoveryEnabled(boolean errorRecoveryEnabled){
   public boolean getErrorRecoveryEnabled(){
     return this.errorRecoveryEnabled;
   }
+
+  public void setHeaderFileSuffixes(List<String> headerFileSuffixes) {
+      this.headerFileSuffixes = headerFileSuffixes;
+  }
+
+  public void setHeaderFileSuffixes(String[] headerFileSuffixes) {
+    if (headerFileSuffixes != null) {
+      setHeaderFileSuffixes(Arrays.asList(headerFileSuffixes));
+    }
+  }
+
+  public List<String> getHeaderFileSuffixes() {
+    return this.headerFileSuffixes;
+  }
 }

cxx-squid/src/main/java/org/sonar/cxx/api/CxxMetric.java

@@ -31,7 +31,9 @@ public enum CxxMetric implements MetricDef {
   CLASSES,
   COMPLEXITY,
   COMMENT_LINES,
-  COMMENT_BLANK_LINES;
+  COMMENT_BLANK_LINES,
+  PUBLIC_API,
+  PUBLIC_UNDOCUMENTED_API;
 
   public String getName() {
     return name();