Add description to inspections.

.travis.yml

@@ -4,7 +4,6 @@ scala:
    - 2.12.8
    - 2.12.9
    - 2.12.10
-   - 2.13.0
    - 2.13.1
 script:
    - sbt clean test
@@ -24,4 +23,3 @@ cache:
   directories:
     - $HOME/.ivy2/cache
     - $HOME/.sbt/boot/
-

build.sbt

@@ -73,7 +73,7 @@ def check(code: String) = {
   // runner.reporter.reset
   val c = runner compileCodeSnippet code
   val feedback = c.scapegoat.feedback
-  feedback.warnings map (x => "%-40s  %s".format(x.text, x.snippet getOrElse "")) foreach println
+  feedback.warnings map (x => "%-40s %s %s".format(x.text, x.explanation, x.snippet.getOrElse(""))) foreach println
   feedback
 }
 """

src/main/scala/com/sksamuel/scapegoat/Feedback.scala

@@ -20,10 +20,15 @@ class Feedback(consoleOutput: Boolean, reporter: Reporter, sourcePrefix: String,
   def warns = warnings(Levels.Warning)
   def warnings(level: Level): Seq[Warning] = warnings.filter(_.level == level)
 
-  def warn(pos: Position, inspection: Inspection, snippet: Option[String] = None): Unit = {
+  def warn(
+    pos: Position,
+    inspection: Inspection,
+    snippet: Option[String] = None,
+    adhocExplanation: Option[String] = None
+  ): Unit = {
     val level = inspection.defaultLevel
     val text = inspection.text
-    val snippetText = inspection.explanation.orElse(snippet)
+    val explanation = adhocExplanation.getOrElse(inspection.explanation)
     val adjustedLevel = (levelOverridesByInspectionSimpleName.get("all"), levelOverridesByInspectionSimpleName.get(inspection.getClass.getSimpleName)) match {
       case (Some(l), _) => l
       case (None, Some(l)) => l
@@ -32,11 +37,21 @@ class Feedback(consoleOutput: Boolean, reporter: Reporter, sourcePrefix: String,
 
     val sourceFileFull = pos.source.file.path
     val sourceFileNormalized = normalizeSourceFile(sourceFileFull)
-    val warning = Warning(text, pos.line, adjustedLevel, sourceFileFull, sourceFileNormalized, snippetText, inspection.getClass.getCanonicalName)
+    val warning = Warning(
+      text = text,
+      line = pos.line,
+      level = adjustedLevel,
+      sourceFileFull = sourceFileFull,
+      sourceFileNormalized = sourceFileNormalized,
+      snippet = snippet,
+      explanation = explanation,
+      inspection = inspection.getClass.getCanonicalName
+    )
     warningsBuffer.append(warning)
     if (shouldPrint(warning)) {
       println(s"[${warning.level.toString.toLowerCase}] $sourceFileNormalized:${warning.line}: $text")
-      snippetText.foreach(s => println(s"          $s"))
+      println(s"          $explanation")
+      snippet.foreach(s => println(s"          $s"))
       println()
     }
 
@@ -55,14 +70,16 @@ class Feedback(consoleOutput: Boolean, reporter: Reporter, sourcePrefix: String,
   }
 }
 
-case class Warning(text: String,
+case class Warning(
+  text: String,
   line: Int,
   level: Level,
   sourceFileFull: String,
   sourceFileNormalized: String,
   snippet: Option[String],
-  inspection: String) {
-
+  explanation: String,
+  inspection: String
+) {
   def hasMinimalLevelOf(minimalLevel: Level): Boolean = {
     minimalLevel match {
       case Levels.Info => true

src/main/scala/com/sksamuel/scapegoat/Inspection.scala

@@ -4,13 +4,15 @@ import scala.reflect.internal.util.Position
 import scala.tools.nsc.Global
 
 /** @author Stephen Samuel */
-abstract class Inspection(val text: String, val defaultLevel: Level, val explanation: Option[String] = None) {
+abstract class Inspection(
+  val text: String,
+  val defaultLevel: Level,
+  val description: String,
+  val explanation: String
+) {
 
   val self = this
 
-  def this(text: String, defaultLevel: Level, explanation: String) =
-    this(text, defaultLevel, Option(explanation))
-
   def inspector(context: InspectionContext): Inspector
 }
 
@@ -40,13 +42,19 @@ abstract class Inspector(val context: InspectionContext) {
 
 case class InspectionContext(global: Global, feedback: Feedback) {
 
-  def warn(pos: Position, inspection: Inspection, snippet: String): Unit = {
-    feedback.warn(pos, inspection, Some(snippet))
-  }
-
-  def warn(pos: Position, inspection: Inspection): Unit = {
-    feedback.warn(pos, inspection)
-  }
+  def warn(pos: Position, inspection: Inspection): Unit =
+    feedback.warn(pos, inspection, None, None)
+
+  def warn(pos: Position, inspection: Inspection, snippet: String): Unit =
+    feedback.warn(pos, inspection, Some(snippet), None)
+
+  def warn(
+    pos: Position,
+    inspection: Inspection,
+    snippet: String,
+    adhocExplanation: String
+  ): Unit =
+    feedback.warn(pos, inspection, Some(snippet), Some(adhocExplanation))
 
   trait Traverser extends global.Traverser {
 

src/main/scala/com/sksamuel/scapegoat/inspections/AnyUse.scala

@@ -5,25 +5,27 @@ import com.sksamuel.scapegoat.{Inspection, InspectionContext, Inspector, Levels}
 import scala.reflect.internal.Flags
 
 /** @author Stephen Samuel */
-class AnyUse extends Inspection("AnyUse", Levels.Info) {
+class AnyUse extends Inspection(
+  text = "Use of Any",
+  defaultLevel = Levels.Info,
+  description = "Checks for code returning Any.",
+  explanation = "Code returning Any is most likely an indication of a programming error."
+) {
 
   def inspector(context: InspectionContext): Inspector = new Inspector(context) {
     override def postTyperTraverser = Some apply new context.Traverser {
 
       import context.global._
 
-      def warn(tree: Tree) = {
-        context.warn(tree.pos, AnyUse.this,
-          "Use of Any should be avoided: " + tree.toString().take(200))
-      }
-
       override def inspect(tree: Tree): Unit = {
         tree match {
           case DefDef(mods, _, _, _, _, _) if mods.isSynthetic =>
           case DefDef(mods, _, _, _, _, _) if mods.hasFlag(Flags.SetterFlags) =>
           case DefDef(mods, _, _, _, _, _) if mods.hasFlag(Flags.GetterFlags) =>
-          case ValDef(_, _, tpt, _) if tpt.tpe =:= typeOf[Any] => warn(tree)
-          case DefDef(_, _, _, _, tpt, _) if tpt.tpe =:= typeOf[Any] => warn(tree)
+          case ValDef(_, _, tpt, _) if tpt.tpe =:= typeOf[Any] =>
+            context.warn(tree.pos, self, tree.toString.take(200))
+          case DefDef(_, _, _, _, tpt, _) if tpt.tpe =:= typeOf[Any] =>
+            context.warn(tree.pos, self, tree.toString.take(200))
           case _ => continue(tree)
         }
       }

src/main/scala/com/sksamuel/scapegoat/inspections/AvoidToMinusOne.scala

@@ -5,7 +5,12 @@ import com.sksamuel.scapegoat.{Inspection, InspectionContext, Inspector, Levels}
 import scala.runtime.{RichInt, RichLong}
 
 /** @author Stephen Samuel */
-class AvoidToMinusOne extends Inspection("Avoid To Minus One", Levels.Info) {
+class AvoidToMinusOne extends Inspection(
+  text = "Avoid (j to k - 1)",
+  defaultLevel = Levels.Info,
+  description = "Checks for ranges using (j to k - 1).",
+  explanation = "A range in the following format (j to k - 1) can be simplified to (j until k)."
+) {
 
   def inspector(context: InspectionContext): Inspector = new Inspector(context) {
     override def postTyperTraverser = Some apply new context.Traverser {
@@ -24,9 +29,9 @@ class AvoidToMinusOne extends Inspection("Avoid To Minus One", Levels.Info) {
       override def inspect(tree: Tree): Unit = {
         tree match {
           case Apply(TypeApply(Select(Apply(Select(lhs, To),
-            List(Apply(Select(loopvar, Minus), List(Literal(Constant(1)))))), Foreach), _), _) if isIntegral(lhs) && isIntegral(loopvar) =>
-            context.warn(tree.pos, self,
-              "j to k - 1 can be better written as j until k: " + tree.toString().take(200))
+            List(Apply(Select(loopvar, Minus), List(Literal(Constant(1)))))), Foreach), _), _)
+              if isIntegral(lhs) && isIntegral(loopvar) =>
+                context.warn(tree.pos, self, tree.toString.take(200))
           case _ => continue(tree)
         }
       }

src/main/scala/com/sksamuel/scapegoat/inspections/DoubleNegation.scala

@@ -3,7 +3,12 @@ package com.sksamuel.scapegoat.inspections
 import com.sksamuel.scapegoat.{Inspection, InspectionContext, Inspector, Levels}
 
 /** @author Stephen Samuel */
-class DoubleNegation extends Inspection("Double negation", Levels.Info) {
+class DoubleNegation extends Inspection(
+  text = "Double negation",
+  defaultLevel = Levels.Info,
+  description = "Checks for code like !(!b).",
+  explanation = "Double negation can be removed, e.g. !(!b) it equal to just b."
+) {
 
   def inspector(context: InspectionContext): Inspector = new Inspector(context) {
     override def postTyperTraverser = Some apply new context.Traverser {
@@ -15,8 +20,7 @@ class DoubleNegation extends Inspection("Double negation", Levels.Info) {
       override def inspect(tree: Tree): Unit = {
         tree match {
           case Select(Select(_, Bang), Bang) =>
-            context.warn(tree.pos, self,
-              "Double negation can be removed: " + tree.toString().take(200))
+            context.warn(tree.pos, self, tree.toString.take(200))
           case _ => continue(tree)
         }
       }

src/main/scala/com/sksamuel/scapegoat/inspections/EmptyCaseClass.scala

@@ -3,8 +3,12 @@ package com.sksamuel.scapegoat.inspections
 import com.sksamuel.scapegoat.{Inspection, InspectionContext, Inspector, Levels}
 
 /** @author Stephen Samuel */
-class EmptyCaseClass extends Inspection("Empty case class", Levels.Info,
-  "Empty case class can be rewritten as a case object") {
+class EmptyCaseClass extends Inspection(
+  text = "Empty case class",
+  defaultLevel = Levels.Info,
+  description = "Checks for empty case classes like, e.g. case class Faceman().",
+  explanation = "An empty case class can be rewritten as a case object."
+) {
 
   def inspector(context: InspectionContext): Inspector = new Inspector(context) {
     override def postTyperTraverser = Some apply new context.Traverser {

src/main/scala/com/sksamuel/scapegoat/inspections/FinalModifierOnCaseClass.scala

@@ -3,7 +3,11 @@ package com.sksamuel.scapegoat.inspections
 import com.sksamuel.scapegoat.{Inspection, InspectionContext, Inspector, Levels}
 
 class FinalModifierOnCaseClass extends Inspection(
-  "Missing final modifier on case class", Levels.Info, "Case classes should have final modifier") {
+  text = "Missing final modifier on case class",
+  defaultLevel = Levels.Info,
+  description = "Checks for case classes without a final modifier.",
+  explanation = "Using case classes without final modifier can lead to surprising breakage."
+) {
 
   override def inspector(context: InspectionContext): Inspector = new Inspector(context) {
 

src/main/scala/com/sksamuel/scapegoat/inspections/LonelySealedTrait.scala

@@ -5,7 +5,12 @@ import com.sksamuel.scapegoat.{Inspection, InspectionContext, Inspector, Levels}
 import scala.collection.mutable
 
 /** @author Stephen Samuel */
-class LonelySealedTrait extends Inspection("Lonely sealed trait", Levels.Error) {
+class LonelySealedTrait extends Inspection(
+  text = "Lonely sealed trait",
+  defaultLevel = Levels.Error,
+  description = "Checks for sealed traits without any classes extending it.",
+  explanation = "A sealed trait that is not extended is considered dead code."
+) {
 
   override def inspector(context: InspectionContext): Inspector = new Inspector(context) {
 
@@ -17,7 +22,7 @@ class LonelySealedTrait extends Inspection("Lonely sealed trait", Levels.Error)
     override def postInspection(): Unit = {
       for ((name, cdef) <- sealedClasses) {
         if (!implementedClasses.contains(name)) {
-          context.warn(cdef.pos, self, s"Sealed trait ${cdef.name} has no implementing classes")
+          context.warn(cdef.pos, self)
         }
       }
     }

src/main/scala/com/sksamuel/scapegoat/inspections/MaxParameters.scala

@@ -3,7 +3,12 @@ package com.sksamuel.scapegoat.inspections
 import com.sksamuel.scapegoat.{Inspection, InspectionContext, Inspector, Levels}
 
 /** @author Stephen Samuel */
-class MaxParameters extends Inspection("Max parameters", Levels.Info) {
+class MaxParameters extends Inspection(
+  text = "Max parameters",
+  defaultLevel = Levels.Info,
+  description = "Checks for methods that have over 10 parameters.",
+  explanation = "Methods having a large number of parameters are more difficult to reason about, consider refactoring this code."
+) {
 
   def inspector(context: InspectionContext): Inspector = new Inspector(context) {
     override def postTyperTraverser = Some apply new context.Traverser {
@@ -21,8 +26,7 @@ class MaxParameters extends Inspection("Max parameters", Levels.Info) {
           case DefDef(_, name, _, _, _, _) if name == nme.CONSTRUCTOR =>
           case DefDef(mods, _, _, _, _, _) if mods.isSynthetic        =>
           case DefDef(_, name, _, vparamss, _, _) if countExceeds(vparamss, 10) =>
-            context.warn(tree.pos, self,
-              s"Method $name has ${count(vparamss)} parameters. Consider refactoring to a containing instance.")
+            context.warn(tree.pos, self)
           case _ => continue(tree)
         }
       }

src/main/scala/com/sksamuel/scapegoat/inspections/NoOpOverride.scala

@@ -3,7 +3,12 @@ package com.sksamuel.scapegoat.inspections
 import com.sksamuel.scapegoat.{Inspection, InspectionContext, Inspector, Levels}
 
 /** @author Stephen Samuel */
-class NoOpOverride extends Inspection("No op Override", Levels.Info) {
+class NoOpOverride extends Inspection(
+  text = "Noop override",
+  defaultLevel = Levels.Info,
+  description = "Checks for code that overrides parent method but simply calls super.",
+  explanation = "This method is overridden yet only calls super."
+) {
 
   def inspector(context: InspectionContext): Inspector = new Inspector(context) {
     override def postTyperTraverser = Some apply new context.Traverser {
@@ -22,8 +27,7 @@ class NoOpOverride extends Inspection("No op Override", Levels.Info) {
         tree match {
           case DefDef(_, name, _, vparamss, _, Apply(Select(Super(This(_), _), name2), args))
             if name == name2 && vparamss.size == 1 && argumentsMatch(vparamss.head, args) =>
-              context.warn(tree.pos, self,
-                "This method is overridden yet only calls super: " + tree.toString().take(200))
+              context.warn(tree.pos, self, tree.toString.take(200))
           case _ => continue(tree)
         }
       }