Cleaned up and brought up to date the help text...

Cleaned up and brought up to date the help text for -X and -Y options.
Made some enhancements to PhasesSetting, which are documented if you
run scalac -X or -Y. (Try it!) Disabled some dead settings and renamed
others to reflect their current purpose. No review.

14 files changed, 218 insertions, 158 deletions

diff --git a/src/compiler/scala/tools/ant/FastScalac.scala b/src/compiler/scala/tools/ant/FastScalac.scala
index 98e6098f89..f016739a2b 100644
--- a/src/compiler/scala/tools/ant/FastScalac.scala
+++ b/src/compiler/scala/tools/ant/FastScalac.scala
@@ -75,6 +75,12 @@ class FastScalac extends Scalac {
       reset.value = resetCaches
       shutdown.value = shutdownServer
 
+      /** XXX Since fsc is largely unmaintained, the set of options being individually
+       *  assessed here is likely to bear little relationship to the current set of options.
+       *  Most likely this manifests in confusing and very difficult to debug behavior in fsc.
+       *  We should warn or fix.
+       */
+
       val stringSettings =
         List(s.outdir, s.classpath, s.bootclasspath, s.extdirs, s.encoding) flatMap (x => List(x.name, x.value))
 
@@ -85,7 +91,7 @@ class FastScalac extends Scalac {
         List(s.debuginfo, s.target) map (x => "%s:%s".format(x.name, x.value))
 
       val booleanSettings =
-        List(s.debug, s.deprecation, s.nopredefs, s.verbose, reset, shutdown) map (x => if (x.value) List(x.name) else Nil) flatten
+        List(s.debug, s.deprecation, s.verbose, reset, shutdown) map (x => if (x.value) List(x.name) else Nil) flatten
 
       val phaseSetting = {
         val s = settings.log
diff --git a/src/compiler/scala/tools/nsc/CompilerCommand.scala b/src/compiler/scala/tools/nsc/CompilerCommand.scala
index 54ef6bb8be..fe45412a70 100644
--- a/src/compiler/scala/tools/nsc/CompilerCommand.scala
+++ b/src/compiler/scala/tools/nsc/CompilerCommand.scala
@@ -28,19 +28,41 @@ class CompilerCommand(arguments: List[String], val settings: Settings) {
     if (s.length >= helpSyntaxColumnWidth) s
     else s + (" " * (helpSyntaxColumnWidth - s.length))
 
+  private val explainAdvanced = "\n" + """
+    |-- Notes on option parsing --
+    |Boolean settings are always false unless set.
+    |Where multiple values are accepted, they should be comma-separated.
+    |  example: -Xplugin:plugin1,plugin2
+    |<phase> means one or a list of:
+    |  (partial) phase names, phase ids, phase id ranges, or the string "all".
+    |  example: -Xprint:all prints all phases.
+    |  example: -Xprint:expl,24-26 prints phases explicitouter, closelim, dce, jvm.
+    |  example: -Xprint:-4 prints only the phases up to typer.
+    |
+  """.stripMargin.trim + "\n\n"
+
   /** Creates a help message for a subset of options based on cond */
-  def createUsageMsg(label: String, cond: (Setting) => Boolean): String =
-    settings.visibleSettings .
-      filter(cond) .
-      map(s => format(s.helpSyntax) + "  " + s.helpDescription) .
-      toList.sorted.mkString("Usage: %s <options> <source files>\n%s options include:\n  " .
-        format(cmdName, label), "\n  ", "\n")
+  def createUsageMsg(label: String, shouldExplain: Boolean, cond: (Setting) => Boolean): String = {
+    def helpStr(s: Setting) = format(s.helpSyntax) + "  " + s.helpDescription
+
+    val usage         = "Usage: %s <options> <source files>\n" format cmdName
+    val explain       = if (shouldExplain) explainAdvanced else ""
+    val prefix        = label + " options include:\n  "
+
+    // Separating out any debugging options from others for easier reading
+    val (debug, rest) = (settings.visibleSettings filter cond).toList sortBy (_.name) partition (_.isForDebug)
+
+    (rest map helpStr).mkString(usage + explain + prefix, "\n  ", "\n") + (
+      if (debug.isEmpty) ""
+      else (debug map helpStr).mkString("\nAdditional debug settings:\n  ", "\n  ", "\n")
+    )
+  }
 
   /** Messages explaining usage and options */
-  def usageMsg    = createUsageMsg("where possible standard", _.isStandard)
-  def fscUsageMsg = createUsageMsg("where possible standard", ( st => st.isStandard || st.name == "-shutdown"))
-  def xusageMsg   = createUsageMsg("Possible advanced", _.isAdvanced)
-  def yusageMsg   = createUsageMsg("Possible private", _.isPrivate)
+  def usageMsg    = createUsageMsg("where possible standard", false, _.isStandard)
+  def fscUsageMsg = createUsageMsg("where possible standard", false, ( st => st.isStandard || st.name == "-shutdown"))
+  def xusageMsg   = createUsageMsg("Possible advanced", true, _.isAdvanced)
+  def yusageMsg   = createUsageMsg("Possible private", true, _.isPrivate)
 
   // If any of these settings is set, the compiler shouldn't start;
   // an informative message of some sort should be printed instead.
diff --git a/src/compiler/scala/tools/nsc/GenericRunnerSettings.scala b/src/compiler/scala/tools/nsc/GenericRunnerSettings.scala
index 65fdb82bd2..4d40566a95 100644
--- a/src/compiler/scala/tools/nsc/GenericRunnerSettings.scala
+++ b/src/compiler/scala/tools/nsc/GenericRunnerSettings.scala
@@ -18,6 +18,7 @@ extends Settings(error) {
   val howtorun =
     ChoiceSetting(
       "-howtorun",
+      "how",
       "how to run the specified code",
       List("guess", "object", "script"),
       "guess")
diff --git a/src/compiler/scala/tools/nsc/Global.scala b/src/compiler/scala/tools/nsc/Global.scala
index bb0e122dd6..261714452d 100644
--- a/src/compiler/scala/tools/nsc/Global.scala
+++ b/src/compiler/scala/tools/nsc/Global.scala
@@ -203,9 +203,9 @@ class Global(var settings: Settings, var reporter: Reporter) extends SymbolTable
 
   /** Taking flag checking to a somewhat higher level. */
   object opt {
-    // True if the given PhasesSetting includes the current phase.
-    def isActive(ph: Settings#PhasesSetting)  = ph contains globalPhase.name
-    def wasActive(ph: Settings#PhasesSetting) = ph contains globalPhase.prev.name
+    // protected implicit lazy val globalPhaseOrdering: Ordering[Phase] = Ordering[Int] on (_.id)
+    def isActive(ph: Settings#PhasesSetting)  = ph containsPhase globalPhase
+    def wasActive(ph: Settings#PhasesSetting) = ph containsPhase globalPhase.prev
 
     // Some(value) if setting has been set by user, None otherwise.
     def optSetting[T](s: Settings#Setting): Option[T] =
@@ -557,11 +557,11 @@ class Global(var settings: Settings, var reporter: Reporter) extends SymbolTable
       analyzer.typerFactory   -> "the meat and potatoes: type the trees",
       superAccessors          -> "add super accessors in traits and nested classes",
       pickler                 -> "serialize symbol tables",
-      refchecks               -> "reference and override checking, translate nested objects",
+      refchecks               -> "reference/override checking, translate nested objects",
       uncurry                 -> "uncurry, translate function values to anonymous classes",
       tailCalls               -> "replace tail calls by jumps",
       specializeTypes         -> "@specialized-driven class and method specialization",
-      explicitOuter           -> "C.this refs become outer pointers, translate pattern matches",
+      explicitOuter           -> "this refs to outer pointers, translate patterns",
       erasure                 -> "erase types, add interfaces for traits",
       lazyVals                -> "allocate bitmaps, translate lazy vals into lazified defs",
       lambdaLift              -> "move nested functions to top level",
@@ -617,9 +617,14 @@ class Global(var settings: Settings, var reporter: Reporter) extends SymbolTable
   /** A description of the phases that will run */
   def phaseDescriptions: String = {
     val width = phaseNames map (_.length) max
-    val fmt   = "%" + width + "s  %s\n"
+    val fmt   = "%" + width + "s  %2s  %s\n"
 
-    phaseDescriptors map (ph => fmt.format(ph.phaseName, phasesDescMap(ph))) mkString
+    val line1 = fmt.format("phase name", "id", "description")
+    val line2 = fmt.format("----------", "--", "-----------")
+    val descs = phaseDescriptors.zipWithIndex map {
+      case (ph, idx) => fmt.format(ph.phaseName, idx + 1, phasesDescMap(ph))
+    }
+    line1 :: line2 :: descs mkString
   }
 
   // ----------- Runs ---------------------------------------
diff --git a/src/compiler/scala/tools/nsc/Phase.scala b/src/compiler/scala/tools/nsc/Phase.scala
index 6ff932acc2..9726834b88 100644
--- a/src/compiler/scala/tools/nsc/Phase.scala
+++ b/src/compiler/scala/tools/nsc/Phase.scala
@@ -41,6 +41,11 @@ abstract class Phase(val prev: Phase) {
   def run: Unit
 
   override def toString() = name
+  override def hashCode = id.## + name.##
+  override def equals(other: Any) = other match {
+    case x: Phase   => id == x.id && name == x.name
+    case _          => false
+  }
 }
 
 
diff --git a/src/compiler/scala/tools/nsc/doc/Settings.scala b/src/compiler/scala/tools/nsc/doc/Settings.scala
index e567602fae..d4ae1ba42f 100644
--- a/src/compiler/scala/tools/nsc/doc/Settings.scala
+++ b/src/compiler/scala/tools/nsc/doc/Settings.scala
@@ -15,7 +15,7 @@ class Settings(error: String => Unit) extends scala.tools.nsc.Settings(error) {
 
   /** A setting that defines in which format the documentation is output. ''Note:'' this setting is currently always
     * `html`. */
-  val docformat      = ChoiceSetting    ("-doc-format", "Selects in which format documentation is rendered", List("html"), "html")
+  val docformat      = ChoiceSetting    ("-doc-format", "format", "Selects in which format documentation is rendered", List("html"), "html")
 
   /** A setting that defines the overall title of the documentation, typically the name of the library being
     * documented. 'Note:'' This setting is currently not used. */
@@ -31,8 +31,10 @@ class Settings(error: String => Unit) extends scala.tools.nsc.Settings(error) {
 
   val useStupidTypes = BooleanSetting   ("-Yuse-stupid-types", "Print the types of inherited members as seen from their original definition context. Hint: you don't want to do that!")
 
-  // working around issue described in r18708.
-  suppressVTWarn.value = true
+  // Somewhere slightly before r18708 scaladoc stopped building unless the
+  // self-type check was suppressed.  I hijacked the slotted-for-removal-anyway
+  // suppress-vt-warnings option and renamed it for this purpose.
+  noSelfCheck.value = true
 
   // TODO: add a new setting for whether or not to document sourceless entities (e.g., Any, Unit, etc)
 }
diff --git a/src/compiler/scala/tools/nsc/matching/MatrixAdditions.scala b/src/compiler/scala/tools/nsc/matching/MatrixAdditions.scala
index d30bbfa79c..7a5aa47cbb 100644
--- a/src/compiler/scala/tools/nsc/matching/MatrixAdditions.scala
+++ b/src/compiler/scala/tools/nsc/matching/MatrixAdditions.scala
@@ -28,7 +28,7 @@ trait MatrixAdditions extends ast.TreeDSL
   private[matching] trait Squeezer {
     self: MatrixContext =>
 
-    private val settings_squeeze = settings.Xsqueeze.value == "on"
+    private val settings_squeeze = !settings.Ynosqueeze.value
 
     def squeezedBlockPVs(pvs: List[PatternVar], exp: Tree): Tree =
       squeezedBlock(pvs map (_.valDef), exp)
diff --git a/src/compiler/scala/tools/nsc/settings/AbsScalaSettings.scala b/src/compiler/scala/tools/nsc/settings/AbsScalaSettings.scala
index 2ef73dc9a7..c4e2e93235 100644
--- a/src/compiler/scala/tools/nsc/settings/AbsScalaSettings.scala
+++ b/src/compiler/scala/tools/nsc/settings/AbsScalaSettings.scala
@@ -22,14 +22,14 @@ trait AbsScalaSettings {
   type OutputSetting <: AbsSetting
 
   def BooleanSetting(name: String, descr: String): BooleanSetting
-  def ChoiceSetting(name: String, descr: String, choices: List[String], default: String): ChoiceSetting
+  def ChoiceSetting(name: String, helpArg: String, descr: String, choices: List[String], default: String): ChoiceSetting
   def DefinesSetting(): DefinesSetting
   def IntSetting(name: String, descr: String, default: Int, range: Option[(Int, Int)], parser: String => Option[Int]): IntSetting
-  def MultiStringSetting(name: String, arg: String, descr: String): MultiStringSetting
+  def MultiStringSetting(name: String, helpArg: String, descr: String): MultiStringSetting
   def OutputSetting(outputDirs: OutputDirs, default: String): OutputSetting
-  def PathSetting(name: String, arg: String, descr: String, default: String): PathSetting
+  def PathSetting(name: String, descr: String, default: String): PathSetting
   def PhasesSetting(name: String, descr: String): PhasesSetting
-  def StringSetting(name: String, arg: String, descr: String, default: String): StringSetting
+  def StringSetting(name: String, helpArg: String, descr: String, default: String): StringSetting
 
   /** **/
   abstract class SettingGroup(val prefix: String) extends AbsSetting {
diff --git a/src/compiler/scala/tools/nsc/settings/AbsSettings.scala b/src/compiler/scala/tools/nsc/settings/AbsSettings.scala
index 21608f7f05..7de34fed64 100644
--- a/src/compiler/scala/tools/nsc/settings/AbsSettings.scala
+++ b/src/compiler/scala/tools/nsc/settings/AbsSettings.scala
@@ -116,6 +116,7 @@ trait AbsSettings {
     def isAdvanced  = name match { case "-Y" => true ; case "-X" => false ; case _  => name startsWith "-X" }
     def isPrivate   = name match { case "-Y" => false ; case _  => name startsWith "-Y" }
     def isStandard  = !isAdvanced && !isPrivate
+    def isForDebug  = isPrivate && (name contains ("-debug")) // by convention, i.e. -Ytyper-debug
 
     def compare(that: Setting): Int = name compare that.name
 
diff --git a/src/compiler/scala/tools/nsc/settings/MutableSettings.scala b/src/compiler/scala/tools/nsc/settings/MutableSettings.scala
index 04af436ea3..e4366b8758 100644
--- a/src/compiler/scala/tools/nsc/settings/MutableSettings.scala
+++ b/src/compiler/scala/tools/nsc/settings/MutableSettings.scala
@@ -232,21 +232,21 @@ class MutableSettings(val errorFn: String => Unit) extends AbsSettings with Scal
   }
 
   def BooleanSetting(name: String, descr: String) = add(new BooleanSetting(name, descr))
-  def ChoiceSetting(name: String, descr: String, choices: List[String], default: String) =
-    add(new ChoiceSetting(name, descr, choices, default))
+  def ChoiceSetting(name: String, helpArg: String, descr: String, choices: List[String], default: String) =
+    add(new ChoiceSetting(name, helpArg, descr, choices, default))
   def DefinesSetting() = add(new DefinesSetting())
   def IntSetting(name: String, descr: String, default: Int, range: Option[(Int, Int)], parser: String => Option[Int]) = add(new IntSetting(name, descr, default, range, parser))
   def MultiStringSetting(name: String, arg: String, descr: String) = add(new MultiStringSetting(name, arg, descr))
   def OutputSetting(outputDirs: OutputDirs, default: String) = add(new OutputSetting(outputDirs, default))
   def PhasesSetting(name: String, descr: String) = add(new PhasesSetting(name, descr))
   def StringSetting(name: String, arg: String, descr: String, default: String) = add(new StringSetting(name, arg, descr, default))
-  def PathSetting(name: String, arg: String, descr: String, default: String): PathSetting = {
+  def PathSetting(name: String, descr: String, default: String): PathSetting = {
     val prepend = new StringSetting(name + "/p", "", "", "") with InternalSetting
     val append = new StringSetting(name + "/a", "", "", "") with InternalSetting
 
     add[StringSetting](prepend)
     add[StringSetting](append)
-    add(new PathSetting(name, arg, descr, default, prepend, append))
+    add(new PathSetting(name, descr, default, prepend, append))
   }
 
   // basically this is a value which remembers if it's been modified
@@ -489,12 +489,11 @@ class MutableSettings(val errorFn: String => Unit) extends AbsSettings with Scal
 
   class PathSetting private[nsc](
     name: String,
-    arg: String,
     descr: String,
     default: String,
     prependPath: StringSetting,
     appendPath: StringSetting)
-  extends StringSetting(name, arg, descr, default) {
+  extends StringSetting(name, "path", descr, default) {
     import util.ClassPath.join
     def prepend(s: String) = prependPath.value = join(s, prependPath.value)
     def append(s: String) = appendPath.value = join(appendPath.value, s)
@@ -547,19 +546,19 @@ class MutableSettings(val errorFn: String => Unit) extends AbsSettings with Scal
    */
   class ChoiceSetting private[nsc](
     name: String,
+    helpArg: String,
     descr: String,
     override val choices: List[String],
     val default: String)
-  extends Setting(name, descr + choices.mkString(" (", ",", ")")) {
+  extends Setting(name, descr + choices.mkString(" (", ",", ") default:" + default)) {
     type T = String
     protected var v: String = default
-    protected def argument: String = name drop 1
     def indexOfChoice: Int = choices indexOf value
 
     def tryToSet(args: List[String]) = { value = default ; Some(args) }
 
     override def tryToSetColon(args: List[String]) = args match {
-      case Nil                            => errorAndValue("missing " + argument, None)
+      case Nil                            => errorAndValue("missing " + helpArg, None)
       case List(x) if choices contains x  => value = x ; Some(Nil)
       case List(x)                        => errorAndValue("'" + x + "' is not a valid choice for '" + name + "'", None)
       case xs                             => errorAndValue("'" + name + "' does not accept multiple arguments.", None)
@@ -567,7 +566,7 @@ class MutableSettings(val errorFn: String => Unit) extends AbsSettings with Scal
     def unparse: List[String] =
       if (value == default) Nil else List(name + ":" + value)
 
-    withHelpSyntax(name + ":<" + argument + ">")
+    withHelpSyntax(name + ":<" + helpArg + ">")
   }
 
   /** A setting represented by a list of strings which should be prefixes of
@@ -578,10 +577,33 @@ class MutableSettings(val errorFn: String => Unit) extends AbsSettings with Scal
   class PhasesSetting private[nsc](
     name: String,
     descr: String)
-  extends Setting(name, descr + " <phase> or \"all\"") {
+  extends Setting(name, descr + " <phase>.") {
     type T = List[String]
     protected var v: List[String] = Nil
     override def value = if (v contains "all") List("all") else super.value
+    private lazy val (numericValues, stringValues) =
+      value partition (_ forall (ch => ch.isDigit || ch == '-'))
+
+    /** A little ad-hoc parsing.  If a string is not the name of a phase, it can also be:
+     *    a phase id: 5
+     *    a phase id range: 5-10 (inclusive of both ends)
+     *    a range with no start: -5 means up to and including 5
+     *    a range with no end: 10- means 10 until completion.
+     */
+    private def stringToPhaseIdTest(s: String): Int => Boolean = (s indexOf '-') match {
+      case -1  => (_ == s.toInt)
+      case 0   => (_ <= s.tail.toInt)
+      case idx =>
+        if (s.last == '-') (_ >= s.init.toInt)
+        else (s splitAt idx) match {
+          case (s1, s2) => (id => id >= s1.toInt && id <= s2.tail.toInt)
+        }
+    }
+    private lazy val phaseIdTest: Int => Boolean =
+      (numericValues map stringToPhaseIdTest) match {
+        case Nil    => _ => false
+        case fns    => fns.reduceLeft((f1, f2) => id => f1(id) || f2(id))
+      }
 
     def tryToSet(args: List[String]) = errorAndValue("missing phase", None)
     override def tryToSetColon(args: List[String]) = args match {
@@ -590,11 +612,13 @@ class MutableSettings(val errorFn: String => Unit) extends AbsSettings with Scal
     }
     // we slightly abuse the usual meaning of "contains" here by returning
     // true if our phase list contains "all", regardless of the incoming argument
-    def contains(phasename: String): Boolean =
-      doAllPhases || (value exists { phasename startsWith _ } )
+    def contains(phName: String)     = doAllPhases || containsName(phName)
+    def containsName(phName: String) = stringValues exists (phName startsWith _)
+    def containsId(phaseId: Int)     = phaseIdTest(phaseId)
+    def containsPhase(ph: Phase)     = contains(ph.name) || containsId(ph.id)
 
-    def doAllPhases() = value contains "all"
-    def unparse: List[String] = value map { name + ":" + _ }
+    def doAllPhases = stringValues contains "all"
+    def unparse: List[String] = value map (name + ":" + _)
 
     withHelpSyntax(name + ":<phase>")
   }
diff --git a/src/compiler/scala/tools/nsc/settings/ScalaSettings.scala b/src/compiler/scala/tools/nsc/settings/ScalaSettings.scala
index c25292ccae..37e595fba1 100644
--- a/src/compiler/scala/tools/nsc/settings/ScalaSettings.scala
+++ b/src/compiler/scala/tools/nsc/settings/ScalaSettings.scala
@@ -24,16 +24,11 @@ trait ScalaSettings extends AbsScalaSettings with StandardScalaSettings {
   def disable(s: Setting) = allSettings -= s
 
   /**
-   *  Temporary Settings
-   */
-  val suppressVTWarn = BooleanSetting    ("-Ysuppress-vt-typer-warnings", "Suppress warnings from the typer when testing the virtual class encoding, NOT FOR FINAL!")
-
-  /**
    *  Standard settings
    */
   // argfiles is only for the help message
   val argfiles      = BooleanSetting    ("@<file>", "A text file containing compiler arguments (options and source files)")
-  val classpath     = PathSetting       ("-classpath", "path", "Specify where to find user class files", scalaUserClassPath) .
+  val classpath     = PathSetting       ("-classpath", "Specify where to find user class files.", scalaUserClassPath) .
                                             withAbbreviation ("-cp")
   val d             = OutputSetting     (outputDirs, ".")
   val defines       = DefinesSetting()
@@ -42,52 +37,52 @@ trait ScalaSettings extends AbsScalaSettings with StandardScalaSettings {
                                             withPostSetHook(set => List(inline, Xcloselim, Xdce) foreach (_.value = set.value))
   val nospecialization = BooleanSetting    ("-no-specialization", "Ignore @specialize annotations.")
 
-
   /**
    * -X "Advanced" settings
    */
-  val Xhelp         = BooleanSetting    ("-X", "Print a synopsis of advanced options")
-  val assemname     = StringSetting     ("-Xassem-name", "file", "Name of the output assembly (only relevant with -target:msil)", "").dependsOn(target, "msil")
-  val assemrefs     = StringSetting     ("-Xassem-path", "path", "List of assemblies referenced by the program (only relevant with -target:msil)", ".").dependsOn(target, "msil")
-  val assemextdirs  = StringSetting     ("-Xassem-extdirs", "dirs", "List of directories containing assemblies, defaults to `lib'", Defaults.scalaLibDir.path).dependsOn(target, "msil")
-  val sourcedir     = StringSetting     ("-Xsourcedir", "directory", "When -target:msil, the source folder structure is mirrored in output directory.", ".").dependsOn(target, "msil")
-  val checkInit     = BooleanSetting    ("-Xcheckinit", "Add runtime checks on field accessors. Uninitialized accesses result in an exception being thrown.")
-  val noassertions  = BooleanSetting    ("-Xdisable-assertions", "Generate no assertions and assumptions")
+  val Xhelp         = BooleanSetting    ("-X", "Print a synopsis of advanced options.")
+  val assemname     = StringSetting     ("-Xassem-name", "file", "(Requires -target:msil) Name of the output assembly.", "").dependsOn(target, "msil")
+  val assemrefs     = StringSetting     ("-Xassem-path", "path", "(Requires -target:msil) List of assemblies referenced by the program.", ".").dependsOn(target, "msil")
+  val assemextdirs  = StringSetting     ("-Xassem-extdirs", "dirs", "(Requires -target:msil) List of directories containing assemblies.  default:lib", Defaults.scalaLibDir.path).dependsOn(target, "msil")
+  val sourcedir     = StringSetting     ("-Xsourcedir", "directory", "(Requires -target:msil) Mirror source folder structure in output directory.", ".").dependsOn(target, "msil")
+  val checkInit     = BooleanSetting    ("-Xcheckinit", "Wrap field accessors to throw an exception on uninitialized access.")
+  val noassertions  = BooleanSetting    ("-Xdisable-assertions", "Generate no assertions or assumptions.")
   val elidebelow    = IntSetting        ("-Xelide-below", "Generate calls to @elidable-marked methods only if method priority is greater than argument.",
                                                 elidable.ASSERTION, None, elidable.byName.get(_))
-  val noForwarders  = BooleanSetting    ("-Xno-forwarders", "Do not generate static forwarders in mirror classes")
-  val future        = BooleanSetting    ("-Xfuture", "Turn on future language features")
-  val genPhaseGraph = StringSetting     ("-Xgenerate-phase-graph", "file", "Generate the phase graphs (outputs .dot files) to fileX.dot", "")
-  val XlogImplicits = BooleanSetting    ("-Xlog-implicits", "Show more info on why some implicits are not applicable")
-  val Xmigration28  = BooleanSetting    ("-Xmigration", "Warn about constructs whose behavior may have changed between 2.7 and 2.8")
-  val nouescape     = BooleanSetting    ("-Xno-uescape", "Disables handling of \\u unicode escapes")
-  val Xnojline      = BooleanSetting    ("-Xnojline", "Do not use JLine for editing")
-  val plugin        = MultiStringSetting("-Xplugin", "file", "Load a plugin from a file")
-  val disable       = MultiStringSetting("-Xplugin-disable", "plugin", "Disable a plugin")
-  val showPlugins   = BooleanSetting    ("-Xplugin-list", "Print a synopsis of loaded plugins")
-  val require       = MultiStringSetting("-Xplugin-require", "plugin", "Abort unless a plugin is available")
-  val pluginsDir    = StringSetting     ("-Xpluginsdir", "path", "Path to search compiler plugins", Defaults.scalaPluginPath)
+  val noForwarders  = BooleanSetting    ("-Xno-forwarders", "Do not generate static forwarders in mirror classes.")
+  val future        = BooleanSetting    ("-Xfuture", "Turn on future language features.")
+  val genPhaseGraph = StringSetting     ("-Xgenerate-phase-graph", "file", "Generate the phase graphs (outputs .dot files) to fileX.dot.", "")
+  val XlogImplicits = BooleanSetting    ("-Xlog-implicits", "Show more detail on why some implicits are not applicable.")
+  val Xmigration28  = BooleanSetting    ("-Xmigration", "Warn about constructs whose behavior may have changed between 2.7 and 2.8.")
+  val nouescape     = BooleanSetting    ("-Xno-uescape", "Disable handling of \\u unicode escapes.")
+  val Xnojline      = BooleanSetting    ("-Xnojline", "Do not use JLine for editing.")
+  val plugin        = MultiStringSetting("-Xplugin", "file", "Load one or more plugins from files.")
+  val disable       = MultiStringSetting("-Xplugin-disable", "plugin", "Disable the given plugin(s).")
+  val showPlugins   = BooleanSetting    ("-Xplugin-list", "Print a synopsis of loaded plugins.")
+  val require       = MultiStringSetting("-Xplugin-require", "plugin", "Abort unless the given plugin(s) are available.")
+  val pluginsDir    = StringSetting     ("-Xpluginsdir", "path", "Path to search compiler plugins.", Defaults.scalaPluginPath)
   val Xprint        = PhasesSetting     ("-Xprint", "Print out program after")
-  val writeICode    = BooleanSetting    ("-Xprint-icode", "Log internal icode to *.icode files")
-  val Xprintpos     = BooleanSetting    ("-Xprint-pos", "Print tree positions (as offsets)")
-  val printtypes    = BooleanSetting    ("-Xprint-types", "Print tree types (debugging option)")
-  val prompt        = BooleanSetting    ("-Xprompt", "Display a prompt after each error (debugging option)")
-  val resident      = BooleanSetting    ("-Xresident", "Compiler stays resident, files to compile are read from standard input")
-  val script        = StringSetting     ("-Xscript", "object", "Compile as a script, wrapping the code into object.main()", "")
-  val Xshowcls      = StringSetting     ("-Xshow-class", "class", "Show class info", "")
-  val Xshowobj      = StringSetting     ("-Xshow-object", "object", "Show object info", "")
-  val showPhases    = BooleanSetting    ("-Xshow-phases", "Print a synopsis of compiler phases")
-  val sourceReader  = StringSetting     ("-Xsource-reader", "classname", "Specify a custom method for reading source files", "")
+  val writeICode    = BooleanSetting    ("-Xprint-icode", "Log internal icode to *.icode files.")
+  val Xprintpos     = BooleanSetting    ("-Xprint-pos", "Print tree positions, as offsets.")
+  val printtypes    = BooleanSetting    ("-Xprint-types", "Print tree types (debugging option).")
+  val prompt        = BooleanSetting    ("-Xprompt", "Display a prompt after each error (debugging option).")
+  val resident      = BooleanSetting    ("-Xresident", "Compiler stays resident: read source filenames from standard input.")
+  val script        = StringSetting     ("-Xscript", "object", "Treat the source file as a script and wrap it in a main method.", "")
+  val Xshowcls      = StringSetting     ("-Xshow-class", "class", "Show internal representation of class.", "")
+  val Xshowobj      = StringSetting     ("-Xshow-object", "object", "Show internal representation of object.", "")
+  val showPhases    = BooleanSetting    ("-Xshow-phases", "Print a synopsis of compiler phases.")
+  val sourceReader  = StringSetting     ("-Xsource-reader", "classname", "Specify a custom method for reading source files.", "")
 
   val Xwarnfatal    = BooleanSetting    ("-Xfatal-warnings", "Fail the compilation if there are any warnings.")
-  val Xwarninit     = BooleanSetting    ("-Xwarninit", "Warn about possible changes in initialization semantics")
-  val Xchecknull    = BooleanSetting    ("-Xcheck-null", "Emit warning on selection of nullable reference")
+  val Xwarninit     = BooleanSetting    ("-Xwarninit", "Warn about possible changes in initialization semantics.")
+  val Xchecknull    = BooleanSetting    ("-Xcheck-null", "Emit warning on selection of nullable reference.")
 
   // Experimental Extensions
-  val Xexperimental = BooleanSetting    ("-Xexperimental", "Enable experimental extensions") .
+  val Xexperimental = BooleanSetting    ("-Xexperimental", "Enable experimental extensions.") .
                           withPostSetHook(set => List(YdepMethTpes, YmethodInfer) foreach (_.value = set.value)) //YvirtClasses,
-  val YdepMethTpes  = BooleanSetting    ("-Ydependent-method-types", "Allow dependent method types")
-  val YmethodInfer  = BooleanSetting    ("-Yinfer-argument-types", "Infer types for arguments of overriden methods")
+  val YdepMethTpes  = BooleanSetting    ("-Ydependent-method-types", "Allow dependent method types.")
+  val YmethodInfer  = BooleanSetting    ("-Yinfer-argument-types", "Infer types for arguments of overriden methods.")
+  val noSelfCheck   = BooleanSetting    ("-Yno-self-type-checks", "Suppress check for self-type conformance among inherited members.")
   val YvirtClasses  = false // too embryonic to even expose as a -Y //BooleanSetting    ("-Yvirtual-classes", "Support virtual classes")
 
   /** Compatibility stubs for options whose value name did
@@ -103,53 +98,50 @@ trait ScalaSettings extends AbsScalaSettings with StandardScalaSettings {
   /**
    * -Y "Private" settings
    */
-  val Yhelp         = BooleanSetting    ("-Y", "Print a synopsis of private options")
+  val Yhelp         = BooleanSetting    ("-Y", "Print a synopsis of private options.")
   val browse        = PhasesSetting     ("-Ybrowse", "Browse the abstract syntax tree after")
   val check         = PhasesSetting     ("-Ycheck", "Check the tree at the end of")
-  val Yshow         = PhasesSetting     ("-Yshow", "Specifies show phases in conjunction with -Xshow-class or -Xshow-object")
-  val Xcloselim     = BooleanSetting    ("-Yclosure-elim", "Perform closure elimination")
-  val Ycompacttrees = BooleanSetting    ("-Ycompact-trees", "Use compact tree printer when displaying trees")
-  val noCompletion  = BooleanSetting    ("-Yno-completion", "Disable tab-completion in the REPL")
-  val Xdce          = BooleanSetting    ("-Ydead-code", "Perform dead code elimination")
-  val debug         = BooleanSetting    ("-Ydebug", "Output debugging messages")
+  val Yshow         = PhasesSetting     ("-Yshow", "(Requires -Xshow-class or -Xshow-object) Show after")
+  val Xcloselim     = BooleanSetting    ("-Yclosure-elim", "Perform closure elimination.")
+  val Ycompacttrees = BooleanSetting    ("-Ycompact-trees", "Use compact tree printer when displaying trees.")
+  val noCompletion  = BooleanSetting    ("-Yno-completion", "Disable tab-completion in the REPL.")
+  val Xdce          = BooleanSetting    ("-Ydead-code", "Perform dead code elimination.")
+  val debug         = BooleanSetting    ("-Ydebug", "Increase the quantity of debugging output.")
   // val doc           = BooleanSetting    ("-Ydoc", "Generate documentation")
-  val inline        = BooleanSetting    ("-Yinline", "Perform inlining when possible")
-  val Xlinearizer   = ChoiceSetting     ("-Ylinearizer", "Linearizer to use", List("normal", "dfs", "rpo", "dump"), "rpo") .
-                                          withHelpSyntax("-Ylinearizer:<which>")
-  val log           = PhasesSetting     ("-Ylog", "Log operations in")
+  val inline        = BooleanSetting    ("-Yinline", "Perform inlining when possible.")
+  val Xlinearizer   = ChoiceSetting     ("-Ylinearizer", "which", "Linearizer to use", List("normal", "dfs", "rpo", "dump"), "rpo")
+  val log           = PhasesSetting     ("-Ylog", "Log operations during")
   val Ylogcp        = BooleanSetting    ("-Ylog-classpath", "Output information about what classpath is being applied.")
-  val Ynogenericsig = BooleanSetting    ("-Yno-generic-signatures", "Suppress generation of generic signatures for Java")
-  val noimports     = BooleanSetting    ("-Yno-imports", "Compile without any implicit imports")
-  val nopredefs     = BooleanSetting    ("-Yno-predefs", "Compile without any implicit predefined values")
-  val Yprofile      = PhasesSetting     ("-Yprofile", "Profile the given phase. Needs yjpagent to run.")
-  val YprofileClass = StringSetting     ("-Yprofile-class", "class", "Name of profiler class", "scala.tools.util.YourkitProfiling")
-  val Yrecursion    = IntSetting        ("-Yrecursion", "Recursion depth used when locking symbols", 0, Some(0, Int.MaxValue), (_: String) => None)
-  val selfInAnnots  = BooleanSetting    ("-Yself-in-annots", "Include a \"self\" identifier inside of annotations")
-  val Xshowtrees    = BooleanSetting    ("-Yshow-trees", "Show detailed trees when used in connection with -Xprint:<phase>")
+  val Ynogenericsig = BooleanSetting    ("-Yno-generic-signatures", "Suppress generation of generic signatures for Java.")
+  val noimports     = BooleanSetting    ("-Yno-imports", "Compile without any implicit imports.")
+  // Not actually doing anything, so disabled.
+  // val nopredefs     = BooleanSetting    ("-Yno-predefs", "Compile without any implicit predefined values.")
+  val Yprofile      = PhasesSetting     ("-Yprofile", "(Requires jvm -agentpath to contain yjgpagent) Profile")
+  val YprofileClass = StringSetting     ("-Yprofile-class", "class", "Name of profiler class.", "scala.tools.util.YourkitProfiling")
+  val Yrecursion    = IntSetting        ("-Yrecursion", "Set recursion depth used when locking symbols.", 0, Some(0, Int.MaxValue), (_: String) => None)
+  val selfInAnnots  = BooleanSetting    ("-Yself-in-annots", "Include a \"self\" identifier inside of annotations.")
+  val Xshowtrees    = BooleanSetting    ("-Yshow-trees", "(Requires -Xprint:) Print detailed ASTs.")
   val skip          = PhasesSetting     ("-Yskip", "Skip")
-  val Xsqueeze      = ChoiceSetting     ("-Ysqueeze", "if on, creates compact code in matching", List("on","off"), "on") .
-                                          withHelpSyntax("-Ysqueeze:<enabled>")
-  val Ystatistics   = BooleanSetting    ("-Ystatistics", "Print compiler statistics") .
+  val Ynosqueeze    = BooleanSetting    ("-Yno-squeeze", "Disable creation of compact code in matching.")
+  val Ystatistics   = BooleanSetting    ("-Ystatistics", "Print compiler statistics.") .
                                           withPostSetHook(set => util.Statistics.enabled = set.value)
   val stop          = PhasesSetting     ("-Ystop", "Stop after phase")
   val refinementMethodDispatch =
-                      ChoiceSetting     ("-Ystruct-dispatch", "Selects dispatch method for structural refinement method calls",
-                        List("no-cache", "mono-cache", "poly-cache", "invoke-dynamic"), "poly-cache") .
-                        withHelpSyntax("-Ystruct-dispatch:<method>")
+                      ChoiceSetting     ("-Ystruct-dispatch", "policy", "structural method dispatch policy",
+                        List("no-cache", "mono-cache", "poly-cache", "invoke-dynamic"), "poly-cache")
   val Yrangepos     = BooleanSetting    ("-Yrangepos", "Use range positions for syntax trees.")
   val YrichExes     = BooleanSetting    ("-Yrich-exceptions", "More revealing exceptions.  Set SOURCEPATH to java/scala source jars.")
   val Yidedebug     = BooleanSetting    ("-Yide-debug", "Generate, validate and output trees using the interactive compiler.")
-  val Ybuilderdebug = ChoiceSetting     ("-Ybuilder-debug", "Compile using the specified build manager", List("none", "refined", "simple"), "none") .
-                        withHelpSyntax("-Ybuilder-debug:<method>")
+  val Ybuilderdebug = ChoiceSetting     ("-Ybuilder-debug", "manager", "Compile using the specified build manager.", List("none", "refined", "simple"), "none")
   val Ybuildmanagerdebug =
                       BooleanSetting    ("-Ybuild-manager-debug", "Generate debug information for the Refined Build Manager compiler.")
-  val Ytyperdebug   = BooleanSetting    ("-Ytyper-debug", "Trace all type assignements")
+  val Ytyperdebug   = BooleanSetting    ("-Ytyper-debug", "Trace all type assignements.")
   val Ypmatdebug    = BooleanSetting    ("-Ypmat-debug", "Trace all pattern matcher activity.")
   val Yrepldebug    = BooleanSetting    ("-Yrepl-debug", "Trace all repl activity.")
   val Ycompletion   = BooleanSetting    ("-Ycompletion-debug", "Trace all tab completion activity.")
-  val Ypmatnaive    = BooleanSetting    ("-Ypmat-naive", "Desugar matches as naively as possible..")
+  val Ypmatnaive    = BooleanSetting    ("-Ypmat-naive", "Desugar matches as naively as possible.")
   val Ymurmur       = BooleanSetting    ("-Ymurmur", "Use Murmur hash algorithm for case class generated hashCodes.")
-  val Ynotnull      = BooleanSetting    ("-Ynotnull", "Enable the experimental and incomplete scala.NotNull")
+  val Ynotnull      = BooleanSetting    ("-Ynotnull", "Enable (experimental and incomplete) scala.NotNull.")
 
   // Warnings
   val Ywarndeadcode = BooleanSetting    ("-Ywarn-dead-code", "Emit warnings for dead code")
diff --git a/src/compiler/scala/tools/nsc/settings/StandardScalaSettings.scala b/src/compiler/scala/tools/nsc/settings/StandardScalaSettings.scala
index dcefd8bb16..118daed7ff 100644
--- a/src/compiler/scala/tools/nsc/settings/StandardScalaSettings.scala
+++ b/src/compiler/scala/tools/nsc/settings/StandardScalaSettings.scala
@@ -18,33 +18,32 @@ trait StandardScalaSettings {
 
   /** Path related settings.
    */
-  val bootclasspath =     PathSetting ("-bootclasspath", "path", "Override location of bootstrap class files", Defaults.scalaBootClassPath)
+  val bootclasspath =     PathSetting ("-bootclasspath", "Override location of bootstrap class files.", Defaults.scalaBootClassPath)
   val classpath:          PathSetting // is mutated directly in various places (thus inspiring this very effort)
   val d:                OutputSetting // depends on mutable OutputDirs class
-  val extdirs =           PathSetting ("-extdirs", "dirs", "Override location of installed extensions", Defaults.scalaExtDirs)
-  val javabootclasspath = PathSetting ("-javabootclasspath", "path", "Override java boot classpath.", Defaults.javaBootClassPath)
-  val javaextdirs =       PathSetting ("-javaextdirs", "path", "Override java extdirs classpath.", Defaults.javaExtDirs)
-  val sourcepath =        PathSetting ("-sourcepath", "path", "Specify where to find input source files", "") // Defaults.scalaSourcePath
+  val extdirs =           PathSetting ("-extdirs", "Override location of installed extensions.", Defaults.scalaExtDirs)
+  val javabootclasspath = PathSetting ("-javabootclasspath", "Override java boot classpath.", Defaults.javaBootClassPath)
+  val javaextdirs =       PathSetting ("-javaextdirs", "Override java extdirs classpath.", Defaults.javaExtDirs)
+  val sourcepath =        PathSetting ("-sourcepath", "Specify location(s) of source files.", "") // Defaults.scalaSourcePath
 
   /** Other settings.
    */
-  val dependencyfile =  StringSetting ("-dependencyfile", "file", "Specify the file in which dependencies are tracked", ".scala_dependencies")
-  val deprecation =    BooleanSetting ("-deprecation", "Output source locations where deprecated APIs are used")
-  val encoding =        StringSetting ("-encoding", "encoding", "Specify character encoding used by source files", Properties.sourceEncoding)
-  val explaintypes =   BooleanSetting ("-explaintypes", "Explain type errors in more detail")
-  val g =               ChoiceSetting ("-g", "Specify level of generated debugging info", List("none", "source", "line", "vars", "notailcalls"), "vars")
+  val dependencyfile =  StringSetting ("-dependencyfile", "file", "Set dependency tracking file.", ".scala_dependencies")
+  val deprecation =    BooleanSetting ("-deprecation", "Emit warning and location for usages of deprecated APIs.")
+  val encoding =        StringSetting ("-encoding", "encoding", "Specify character encoding used by source files.", Properties.sourceEncoding)
+  val explaintypes =   BooleanSetting ("-explaintypes", "Explain type errors in more detail.")
+  val g =               ChoiceSetting ("-g", "level", "Set level of generated debugging info.", List("none", "source", "line", "vars", "notailcalls"), "vars")
   val help =           BooleanSetting ("-help", "Print a synopsis of standard options")
-  val make =            ChoiceSetting ("-make", "Specify recompilation detection strategy", List("all", "changed", "immediate", "transitive", "transitivenocp"), "all") .
-                                          withHelpSyntax("-make:<strategy>")
+  val make =            ChoiceSetting ("-make", "policy", "Recompilation detection policy", List("all", "changed", "immediate", "transitive", "transitivenocp"), "all")
   val nowarn =         BooleanSetting ("-nowarn", "Generate no warnings")
   val optimise:        BooleanSetting // depends on post hook which mutates other settings
-  val print =          BooleanSetting ("-print", "Print program with all Scala-specific features removed")
-  val target =          ChoiceSetting ("-target", "Specify for which target object files should be built", List("jvm-1.5", "msil"), "jvm-1.5")
-  val unchecked =      BooleanSetting ("-unchecked", "Enable detailed unchecked warnings")
-  val uniqid =         BooleanSetting ("-uniqid", "Print identifiers with unique names for debugging")
+  val print =          BooleanSetting ("-print", "Print program with Scala-specific features removed.")
+  val target =          ChoiceSetting ("-target", "target", "Specify for which target object files should be built", List("jvm-1.5", "msil"), "jvm-1.5")
+  val unchecked =      BooleanSetting ("-unchecked", "Enable detailed unchecked (erasure) warnings.")
+  val uniqid =         BooleanSetting ("-uniqid", "Uniquely tag all identifiers in debugging output.")
   val usejavacp =      BooleanSetting ("-usejavacp", "Utilize the java.class.path in classpath resolution.")
-  val verbose =        BooleanSetting ("-verbose", "Output messages about what the compiler is doing")
-  val version =        BooleanSetting ("-version", "Print product version and exit")
+  val verbose =        BooleanSetting ("-verbose", "Output messages about what the compiler is doing.")
+  val version =        BooleanSetting ("-version", "Print product version and exit.")
 
   /** These are @<file> and -Dkey=val style settings, which don't
    *  nicely map to identifiers.
diff --git a/src/compiler/scala/tools/nsc/typechecker/Typers.scala b/src/compiler/scala/tools/nsc/typechecker/Typers.scala
index 65ce41c020..8ce26c92a1 100644
--- a/src/compiler/scala/tools/nsc/typechecker/Typers.scala
+++ b/src/compiler/scala/tools/nsc/typechecker/Typers.scala
@@ -1247,9 +1247,10 @@ trait Typers { self: Analyzer =>
           }
           if (!(selfType <:< parent.tpe.typeOfThis) &&
               !phase.erasedTypes &&
-              !context.owner.isSynthetic && // don't do this check for synthetic concrete classes for virtuals (part of DEVIRTUALIZE)
-              !(settings.suppressVTWarn.value) &&
-              !selfType.isErroneous && !parent.tpe.isErroneous)
+              !context.owner.isSynthetic &&   // don't check synthetic concrete classes for virtuals (part of DEVIRTUALIZE)
+              !settings.noSelfCheck.value &&  // setting to suppress this very check
+              !selfType.isErroneous &&
+              !parent.tpe.isErroneous)
           {
             //Console.println(context.owner);//DEBUG
             //Console.println(context.owner.unsafeTypeParams);//DEBUG
diff --git a/test/files/run/programmatic-main.check b/test/files/run/programmatic-main.check
index 6cf6fa8ca6..b2c2b8546d 100644
--- a/test/files/run/programmatic-main.check
+++ b/test/files/run/programmatic-main.check
@@ -1,26 +1,28 @@
-        parser  parse source into ASTs, perform simple desugaring
-         namer  resolve names, attach symbols to named trees
-packageobjects  load package objects
-         typer  the meat and potatoes: type the trees
-superaccessors  add super accessors in traits and nested classes
-       pickler  serialize symbol tables
-     refchecks  reference and override checking, translate nested objects
-      liftcode  reify trees
-       uncurry  uncurry, translate function values to anonymous classes
-     tailcalls  replace tail calls by jumps
-    specialize  @specialized-driven class and method specialization
- explicitouter  C.this refs become outer pointers, translate pattern matches
-       erasure  erase types, add interfaces for traits
-      lazyvals  allocate bitmaps, translate lazy vals into lazified defs
-    lambdalift  move nested functions to top level
-  constructors  move field definitions into constructors
-       flatten  eliminate inner classes
-         mixin  mixin composition
-       cleanup  platform-specific cleanups, generate reflective calls
-         icode  generate portable intermediate code
-       inliner  optimization: do inlining
-      closelim  optimization: eliminate uncalled closures
-           dce  optimization: eliminate dead code
-           jvm  generate JVM bytecode
-      terminal  The last phase in the compiler chain
+    phase name  id  description
+    ----------  --  -----------
+        parser   1  parse source into ASTs, perform simple desugaring
+         namer   2  resolve names, attach symbols to named trees
+packageobjects   3  load package objects
+         typer   4  the meat and potatoes: type the trees
+superaccessors   5  add super accessors in traits and nested classes
+       pickler   6  serialize symbol tables
+     refchecks   7  reference and override checking, translate nested objects
+      liftcode   8  reify trees
+       uncurry   9  uncurry, translate function values to anonymous classes
+     tailcalls  10  replace tail calls by jumps
+    specialize  11  @specialized-driven class and method specialization
+ explicitouter  12  this refs to outer pointers, translate patterns
+       erasure  13  erase types, add interfaces for traits
+      lazyvals  14  allocate bitmaps, translate lazy vals into lazified defs
+    lambdalift  15  move nested functions to top level
+  constructors  16  move field definitions into constructors
+       flatten  17  eliminate inner classes
+         mixin  18  mixin composition
+       cleanup  19  platform-specific cleanups, generate reflective calls
+         icode  20  generate portable intermediate code
+       inliner  21  optimization: do inlining
+      closelim  22  optimization: eliminate uncalled closures
+           dce  23  optimization: eliminate dead code
+           jvm  24  generate JVM bytecode
+      terminal  25  The last phase in the compiler chain