Add scaladoc to levels

modules/cli-options/src/main/scala/scala/cli/commands/SpecificationLevel.scala

@@ -6,15 +6,53 @@ import os.copy
 sealed trait SpecificationLevel extends Product with Serializable {
   def md = toString() + " have"
 }
+
+/** Specification levels in the context of Scala CLI runner specification. For more refer to
+  * [SIP-46](https://github.com/scala/improvement-proposals/pull/46)
+  *
+  * Levels are also used to mark if given option, directive or command is part of stable API.
+  */
 object SpecificationLevel {
-  case object MUST   extends SpecificationLevel
+
+  /** Marks option, directive or command that MUST be a part of any Scala Runner Specification (in
+    * RFC meaning). Annotated thing will be included in a new `scala` command.
+    *
+    * This also means that that thing should be sable and we need to support it.
+    */
+  case object MUST extends SpecificationLevel
+
+  /** Marks option, directive or command that SHOULD be a part of any Scala Runner Specification (in
+    * RFC meaning). Annotated thing will be included in a new `scala` command.
+    *
+    * This also means that that thing should be sable and we need to support it.
+    */
   case object SHOULD extends SpecificationLevel
+
+  /** Marks option, directive or command that is an implementation details of Scala CLI and will not
+    * be a part of any Scala Runner Specification. Annotated thing will be included in a new `scala`
+    * command.
+    *
+    * This also means that that thing should be sable and we need to support it.
+    */
   case object IMPLEMENTATION extends SpecificationLevel {
     override def md = toString() + " specific"
   }
+
+  /** Annotated option, directive or command will not be a part of the Scala Runner Specification
+    * and will not be avialiable in the new `scala` command.
+    *
+    * This also means that that thing should be sable and we need to support it.
+    */
   case object RESTRICTED extends SpecificationLevel {
     override def md = "Scala CLI specific"
   }
+
+  /** Annotated option, directive or command will not be a part of the Scala Runner Specification
+    * and will not be avialiable in the new `scala` command.
+    *
+    * Experimental option are not guarantee to be supported in upcoming versions of Scala CLI and
+    * all new options should be experimental.
+    */
   case object EXPERIMENTAL extends SpecificationLevel {
     override def md: String = toString()
   }

modules/cli/src/main/scala/scala/cli/commands/Shebang.scala

@@ -8,7 +8,7 @@ import scala.cli.CurrentParams
 object Shebang extends ScalaCommand[ShebangOptions] {
   override def stopAtFirstUnrecognized: Boolean = true
 
-  override def scalaSpecificationLevel          = SpecificationLevel.MUST
+  override def scalaSpecificationLevel = SpecificationLevel.MUST
 
   override def sharedOptions(options: ShebangOptions): Option[SharedOptions] =
     Run.sharedOptions(options.runOptions)

modules/generate-reference-doc/src/main/scala/scala/cli/doc/GenerateReferenceDoc.scala

@@ -105,6 +105,15 @@ object GenerateReferenceDoc extends CaseApp[InternalDocOptions] {
       |are assumed to be Scala compiler options and will be propagated to Scala Compiler. This applies to all commands that uses compiler directly or indirectly. 
       |
       |
+      | ## Scalac options that are directly supported in scala CLI (so can be provided as is, without any prefixes etc.):
+      |
+      | - `-encoding`
+      | - `-release`
+      | - `-color`
+      | - `-nowarn`
+      | - `-feature`
+      | - `-deprecation`
+      |
       |""".stripMargin
 
   private def cliOptionsContent(
@@ -230,7 +239,7 @@ object GenerateReferenceDoc extends CaseApp[InternalDocOptions] {
     b.section(
       "Commands and options are marked with MUST and SHOULD (in the RFC style) for ones applicable for Scala Runner.",
       "Options and commands mark as **Implementation** that are needed for smooth running of Scala CLI.",
-      "We recommend for this options and commands to be supported by `scala` command (when based on Scala CLI) but not the part of the Scala Runner specification.``"
+      "We recommend for those options and commands to be supported by the `scala` command (when based on Scala CLI) but not to be a part of the Scala Runner specification."
     )
 
     b.section(

website/docs/reference/cli-options.md

@@ -25,6 +25,15 @@ This is a summary of options that are available for each subcommand of the `scal
 are assumed to be Scala compiler options and will be propagated to Scala Compiler. This applies to all commands that uses compiler directly or indirectly. 
 
 
+ ## Scalac options that are directly supported in scala CLI (so can be provided as is, without any prefixes etc.):
+
+ - `-encoding`
+ - `-release`
+ - `-color`
+ - `-nowarn`
+ - `-feature`
+ - `-deprecation`
+
 
 
 ## Benchmarking options

website/docs/reference/scala-command/cli-options.md

@@ -25,6 +25,15 @@ This is a summary of options that are available for each subcommand of the `scal
 are assumed to be Scala compiler options and will be propagated to Scala Compiler. This applies to all commands that uses compiler directly or indirectly. 
 
 
+ ## Scalac options that are directly supported in scala CLI (so can be provided as is, without any prefixes etc.):
+
+ - `-encoding`
+ - `-release`
+ - `-color`
+ - `-nowarn`
+ - `-feature`
+ - `-deprecation`
+
 
 
 ## Compilation server options

website/docs/reference/scala-command/runner-specification.md

@@ -8,7 +8,7 @@ sidebar_position: 1
 
 Commands and options are marked with MUST and SHOULD (in the RFC style) for ones applicable for Scala Runner.
 Options and commands mark as **Implementation** that are needed for smooth running of Scala CLI.
-We recommend for this options and commands to be supported by `scala` command (when based on Scala CLI) but not the part of the Scala Runner specification.``
+We recommend for those options and commands to be supported by the `scala` command (when based on Scala CLI) but not to be a part of the Scala Runner specification.
 
 The proposed Scala runner specification should contains also supported `Using directives` defined in the dedicated [document](./directives.md)]
 
@@ -30,6 +30,15 @@ The proposed Scala runner specification should contains also supported `Using di
 are assumed to be Scala compiler options and will be propagated to Scala Compiler. This applies to all commands that uses compiler directly or indirectly. 
 
 
+ ## Scalac options that are directly supported in scala CLI (so can be provided as is, without any prefixes etc.):
+
+ - `-encoding`
+ - `-release`
+ - `-color`
+ - `-nowarn`
+ - `-feature`
+ - `-deprecation`
+
 
 
 # MUST have commands