Merge pull request scalastyle#201 from shanielh/master

ScalaDocChecker: Add ignoreTokenTypes option

Author: matthewfarwell

src/main/resources/reference.conf

@@ -284,6 +284,8 @@ scaladoc.label = "Missing or badly formed ScalaDoc: {0}"
 scaladoc.description = "Checks that the ScalaDoc on documentable members is well-formed"
 scaladoc.ignoreRegex.label = "Regular expression"
 scaladoc.ignoreRegex.description = "Class names matching this regular expression will be ignored"
+scaladoc.ignoreTokenTypes.label = "Comma Separated String"
+scaladoc.ignoreTokenTypes.description = "Include the following to ignore : PatDefOrDcl (variables), TmplDef (classes, traits), TypeDefOrDcl (type definitions), FunDefOrDcl (functions)"
 
 disallow.space.after.token.message = "Space after token {0}"
 disallow.space.after.token.label = "Space after tokens"
@@ -340,4 +342,3 @@ todo.comment.label = "TODO/FIXME comment"
 todo.comment.description = "Check for use of TODO/FIXME single line comments"
 todo.comment.words.label = "Word list"
 todo.comment.words.description = "Alternative list of words to look for, separated by |"
-

src/main/resources/scalastyle_definition.xml

@@ -152,6 +152,7 @@
     <checker class="org.scalastyle.scalariform.ScalaDocChecker" id="scaladoc" defaultLevel="warning">
         <parameters>
             <parameter name="ignoreRegex" type="string" default="^$"/>
+						<parameter name="ignoreTokenTypes" type="string" default="^$"/>
         </parameters>
     </checker>
     <checker class="org.scalastyle.scalariform.DisallowSpaceAfterTokenChecker" id="disallow.space.after.token" defaultLevel="warning"/>

src/main/resources/scalastyle_documentation.xml

@@ -839,11 +839,15 @@ To bring consistency with how comments should be formatted, leave a space right
  <justification>
  Scaladoc is generally considered a good thing. Within reason.
  </justification>
+ <extra-description>
+ Ignore tokens is a comma separated string that may include the following : PatDefOrDcl (variables), TmplDef (classes, traits), TypeDefOrDcl (type definitions), FunDefOrDcl (functions)
+ </extra-description>
  <example-configuration>
  <![CDATA[
     <check level="warning" class="org.scalastyle.scalariform.ScalaDocChecker" enabled="true">
       <parameters>
         <parameter name="ignoreRegex">(.*Spec$)|(.*SpecIT$)</parameter>
+        <parameter name="ignoreTokenTypes">PatDefOrDcl,TypeDefOrDcl,FunDefOrDcl,TmplDef</parameter>
       </parameters>
     </check>
  ]]>

src/main/resources/scalastyle_messages.properties

@@ -279,6 +279,8 @@ scaladoc.label = Missing or badly formed ScalaDoc: {0}
 scaladoc.description = Checks that the ScalaDoc on documentable members is well-formed
 scaladoc.ignoreRegex.label = "Regular expression"
 scaladoc.ignoreRegex.description = "Class names matching this regular expression will be ignored"
+scaladoc.ignoreTokenTypes.label = Comma Separated String
+scaladoc.ignoreTokenTypes.description = "Include the following to ignore : PatDefOrDcl (variables), TmplDef (classes, traits), TypeDefOrDcl (type definitions), FunDefOrDcl (functions)"
 
 indentation.message = Use correct indentation
 indentation.label = Use correct indentation

src/main/scala/org/scalastyle/scalariform/ScalaDocChecker.scala

@@ -29,6 +29,7 @@ import _root_.scalariform.lexer.Token
 import _root_.scalariform.lexer.TokenType
 import _root_.scalariform.lexer.Tokens.CLASS
 import _root_.scalariform.parser.AccessModifier
+import _root_.scalariform.parser.AstNode
 import _root_.scalariform.parser.FullDefOrDcl
 import _root_.scalariform.parser.FunDefOrDcl
 import _root_.scalariform.parser.ParamClauses
@@ -54,6 +55,7 @@ class ScalaDocChecker extends CombinedChecker {
   protected val errorKey: String = "scaladoc"
 
   val DefaultIgnoreRegex = "^$"
+  val DefaultIgnoreTokenTypes = ""
 
   val skipPrivate = true
   val skipQualifiedPrivate = false
@@ -62,7 +64,11 @@ class ScalaDocChecker extends CombinedChecker {
 
   override def verify(ast: CombinedAst): List[ScalastyleError] = {
     val tokens = ast.compilationUnit.tokens
+
     val ignoreRegex = getString("ignoreRegex", DefaultIgnoreRegex)
+    val tokensToIgnore = getString("ignoreTokenTypes", DefaultIgnoreTokenTypes).split(",").filterNot(_.isEmpty).toSet
+
+    assertTokensToIgnore(tokensToIgnore)
 
     def trimToTokenOfType(list: List[Token], tokenType: TokenType): List[Token] = {
       if (list.isEmpty) {
@@ -79,7 +85,7 @@ class ScalaDocChecker extends CombinedChecker {
     val ignore = ts.nonEmpty && ts(1).text.matches(ignoreRegex)
     ignore match {
       case true => Nil
-      case false => localVisit(skip = false, HiddenTokens(Nil), ast.lines)(ast.compilationUnit.immediateChildren.head)
+      case false => localVisit(skip = false, HiddenTokens(Nil), ast.lines, tokensToIgnore)(ast.compilationUnit.immediateChildren.head)
     }
   }
 
@@ -179,97 +185,114 @@ class ScalaDocChecker extends CombinedChecker {
    *
    * we do not bother descending down any further
    */
-  private def localVisit(skip: Boolean, fallback: HiddenTokens, lines: Lines)(ast: Any): List[ScalastyleError] = ast match {
-    case t: FullDefOrDcl      =>
-      // private, private[xxx];
-      // protected, protected[xxx];
-
-      // check if we are going to include or skip depending on access modifier
-      val accessModifier = t.modifiers.find {
-        case AccessModifier(_, _) => true
-        case _                    => false
-      }
-      val skip = accessModifier.exists {
-        case AccessModifier(pop, Some(_)) =>
-          if (pop.text == "private") skipQualifiedPrivate else skipQualifiedProtected
-        case AccessModifier(pop, None) =>
-          if (pop.text == "private") skipPrivate else skipProtected
-        case _ =>
-          false
-      }
+  private def localVisit(skip: Boolean, fallback: HiddenTokens, lines: Lines, tokensToIgnore: Set[String])(ast: Any): List[ScalastyleError] = {
 
-      // pick the ScalaDoc "attached" to the modifier, which actually means
-      // ScalaDoc of the following member
-      val scalaDocs = for {
-        token    <- t.tokens
-        comment  <- token.associatedWhitespaceAndComments
-        if comment.token.isScalaDocComment
-      } yield comment
-
-      // descend
-      visit(t, localVisit(skip, HiddenTokens(fallback.tokens ++ scalaDocs), lines))
-    case t: TmplDef      =>
-      // trait Foo, trait Foo[A];
-      // class Foo, class Foo[A](a: A);
-      // case class Foo(), case class Foo[A](a: A);
-      // object Foo;
-      val (_, line) = lines.findLineAndIndex(t.firstToken.offset).get
-
-      // we are checking parameters and type parameters
-      val errors = if (skip) Nil else findScalaDoc(t.firstToken, fallback).
-        map { scalaDoc =>
-          paramErrors(line, t.paramClausesOpt)(scalaDoc) ++
-          tparamErrors(line, t.typeParamClauseOpt)(scalaDoc)
-        }.getOrElse(List(LineError(line, List(Missing))))
-
-      // and we descend, because we're interested in seeing members of the types
-      errors ++ visit(t, localVisit(skip, NoHiddenTokens, lines))
-    case t: FunDefOrDcl  =>
-      // def foo[A, B](a: Int): B = ...
-      val (_, line) = lines.findLineAndIndex(t.firstToken.offset).get
-
-      // we are checking parameters, type parameters and returns
-      val errors = if (skip) Nil else findScalaDoc(t.firstToken, fallback).
-        map { scalaDoc =>
-          paramErrors(line, Some(t.paramClauses))(scalaDoc) ++
-          tparamErrors(line, t.typeParamClauseOpt)(scalaDoc) ++
-          returnErrors(line, t.returnTypeOpt)(scalaDoc)
-        }.
-        getOrElse(List(LineError(line, List(Missing))))
-
-      // we don't descend any further
-      errors
-    case t: TypeDefOrDcl =>
-      // type Foo = ...
-      val (_, line) = lines.findLineAndIndex(t.firstToken.offset).get
-
-      // error is non-existence
-      val errors = if (skip) Nil else findScalaDoc(t.firstToken, fallback).
-        map(_ => Nil).
-        getOrElse(List(LineError(line, List(Missing))))
-
-      // we don't descend any further
-      errors
-
-    case t: PatDefOrDcl  =>
-      // val a = ...
-      // var a = ...
-      val (_, line) = lines.findLineAndIndex(t.valOrVarToken.offset).get
-      val errors = if (skip) Nil else findScalaDoc(t.firstToken, fallback).
-        map(_ => Nil).
-        getOrElse(List(LineError(line, List(Missing))))
-      // we don't descend any further
-      errors
-
-    case t: StatSeq =>
-      localVisit(skip, fallback, lines)(t.firstStatOpt) ++ (
-        for(statOpt <- t.otherStats)
-          yield localVisit(skip, statOpt._1.associatedWhitespaceAndComments, lines)(statOpt._2)
-        ).flatten
-
-    case t: Any          =>
-      // anything else, we descend (unless we stopped above)
-      visit(t, localVisit(skip, fallback, lines))
+    def shouldSkip(node: AstNode) = skip || tokensToIgnore.contains(node.getClass.getSimpleName)
+
+    ast match {
+      case t: FullDefOrDcl =>
+        // private, private[xxx];
+        // protected, protected[xxx];
+
+        // check if we are going to include or skip depending on access modifier
+        val accessModifier = t.modifiers.find {
+          case AccessModifier(_, _) => true
+          case _ => false
+        }
+        val skip = accessModifier.exists {
+          case AccessModifier(pop, Some(_)) =>
+            if (pop.text == "private") skipQualifiedPrivate else skipQualifiedProtected
+          case AccessModifier(pop, None) =>
+            if (pop.text == "private") skipPrivate else skipProtected
+          case _ =>
+            false
+        }
+
+        // pick the ScalaDoc "attached" to the modifier, which actually means
+        // ScalaDoc of the following member
+        val scalaDocs = for {
+          token <- t.tokens
+          comment <- token.associatedWhitespaceAndComments
+          if comment.token.isScalaDocComment
+        } yield comment
+
+        // descend
+        visit(t, localVisit(skip, HiddenTokens(fallback.tokens ++ scalaDocs), lines, tokensToIgnore))
+      case t: TmplDef =>
+        // trait Foo, trait Foo[A];
+        // class Foo, class Foo[A](a: A);
+        // case class Foo(), case class Foo[A](a: A);
+        // object Foo;
+        val (_, line) = lines.findLineAndIndex(t.firstToken.offset).get
+
+        // we are checking parameters and type parameters
+        val errors = if (shouldSkip(t)) Nil
+        else findScalaDoc(t.firstToken, fallback).
+          map { scalaDoc =>
+            paramErrors(line, t.paramClausesOpt)(scalaDoc) ++
+              tparamErrors(line, t.typeParamClauseOpt)(scalaDoc)
+          }.getOrElse(List(LineError(line, List(Missing))))
+
+        // and we descend, because we're interested in seeing members of the types
+        errors ++ visit(t, localVisit(skip, NoHiddenTokens, lines, tokensToIgnore))
+      case t: FunDefOrDcl =>
+        // def foo[A, B](a: Int): B = ...
+        val (_, line) = lines.findLineAndIndex(t.firstToken.offset).get
+
+        // we are checking parameters, type parameters and returns
+        val errors = if (shouldSkip(t)) Nil
+        else findScalaDoc(t.firstToken, fallback).
+          map { scalaDoc =>
+            paramErrors(line, Some(t.paramClauses))(scalaDoc) ++
+              tparamErrors(line, t.typeParamClauseOpt)(scalaDoc) ++
+              returnErrors(line, t.returnTypeOpt)(scalaDoc)
+          }.
+          getOrElse(List(LineError(line, List(Missing))))
+
+        // we don't descend any further
+        errors
+      case t: TypeDefOrDcl =>
+        // type Foo = ...
+        val (_, line) = lines.findLineAndIndex(t.firstToken.offset).get
+
+        // error is non-existence
+        val errors = if (shouldSkip(t)) Nil
+        else findScalaDoc(t.firstToken, fallback).
+          map(_ => Nil).
+          getOrElse(List(LineError(line, List(Missing))))
+
+        // we don't descend any further
+        errors
+
+      case t: PatDefOrDcl =>
+        // val a = ...
+        // var a = ...
+        val (_, line) = lines.findLineAndIndex(t.valOrVarToken.offset).get
+        val errors = if (shouldSkip(t)) Nil
+        else findScalaDoc(t.firstToken, fallback).
+          map(_ => Nil).
+          getOrElse(List(LineError(line, List(Missing))))
+        // we don't descend any further
+        errors
+
+      case t: StatSeq =>
+        localVisit(skip, fallback, lines, tokensToIgnore)(t.firstStatOpt) ++ (
+          for (statOpt <- t.otherStats)
+            yield localVisit(skip, statOpt._1.associatedWhitespaceAndComments, lines, tokensToIgnore)(statOpt._2)
+          ).flatten
+
+      case t: Any =>
+        // anything else, we descend (unless we stopped above)
+        visit(t, localVisit(skip, fallback, lines, tokensToIgnore))
+    }
+  }
+
+  private def assertTokensToIgnore(tokensToIgnore: Iterable[String]): Unit = {
+    val wrongTokensToIgnore = tokensToIgnore.filterNot(availableTokensToIgnore.contains)
+    if (wrongTokensToIgnore.nonEmpty) {
+      throw new IllegalArgumentException(s"ignoreTokenTypes contained wrong types: $wrongTokensToIgnore, " +
+        s"available types are $availableTokensToIgnore")
+    }
   }
 
 }
@@ -278,6 +301,13 @@ class ScalaDocChecker extends CombinedChecker {
  * Contains the ScalaDoc model with trivial parsers
  */
 object ScalaDocChecker {
+
+  private val availableTokensToIgnore = Set(classOf[PatDefOrDcl],
+    classOf[TypeDefOrDcl],
+    classOf[FunDefOrDcl],
+    classOf[TmplDef])
+    .map(_.getSimpleName)
+
   val Missing = "Missing"
   def missingParam(name: String): String = "Missing @param " + name
   def extraParam(name: String): String = "Extra @param " + name

src/test/scala/org/scalastyle/scalariform/ScalaDocCheckerTest.scala

@@ -372,4 +372,18 @@ class ScalaDocCheckerTest extends AssertionsForJUnit with CheckerTest {
     assertErrors(List(lineError(7, List(Missing))), source)
   }
 
+  @Test def ignoreTokenTypes(): Unit = {
+
+    val cases = Seq(Seq("val a = 1", "var a = 2") -> "PatDefOrDcl",
+      Seq("class A", "case class A", "object A", "trait A") -> "TmplDef",
+      Seq("type B = A") -> "TypeDefOrDcl",
+      Seq("def A(): Unit") -> "FunDefOrDcl")
+
+    for ((declerations, ignoreTokenType) <- cases;
+         decleration <- declerations) {
+      assertErrors(Nil, decleration, Map("ignoreTokenTypes" -> ignoreTokenType))
+    }
+  }
+
+
 }