Merge pull request #1297 from romanowski/sip-docs

Add mechanism to restrict options based on description and generate reference docs for SIP
VirtusLab · Sep 12, 2022 · c8fc935 · c8fc935
2 parents 932c942 + 52aca4d
commit c8fc935
Show file tree

Hide file tree

Showing 71 changed files with 2,724 additions and 1,786 deletions.
diff --git a/modules/build/src/main/scala/scala/build/CrossSources.scala b/modules/build/src/main/scala/scala/build/CrossSources.scala
@@ -137,7 +137,7 @@ object CrossSources {
                 elem,
                 logger,
                 maybeRecoverOnError,
-                inputs.withRestrictedFeatures
+                inputs.allowRestrictedFeatures
               ).iterator
             )
             .take(1)

diff --git a/modules/build/src/main/scala/scala/build/Inputs.scala b/modules/build/src/main/scala/scala/build/Inputs.scala
@@ -24,7 +24,7 @@ final case class Inputs(
   mayAppendHash: Boolean,
   workspaceOrigin: Option[WorkspaceOrigin],
   enableMarkdown: Boolean,
-  withRestrictedFeatures: Boolean
+  allowRestrictedFeatures: Boolean
 ) {
 
   def isEmpty: Boolean =
@@ -303,7 +303,7 @@ object Inputs {
     directories: Directories,
     forcedWorkspace: Option[os.Path],
     enableMarkdown: Boolean,
-    withRestrictedFeatures: Boolean
+    allowRestrictedFeatures: Boolean
   ): Inputs = {
 
     assert(validElems.nonEmpty)
@@ -364,7 +364,7 @@ object Inputs {
       mayAppendHash = needsHash,
       workspaceOrigin = Some(workspaceOrigin0),
       enableMarkdown = enableMarkdown,
-      withRestrictedFeatures = withRestrictedFeatures
+      allowRestrictedFeatures = allowRestrictedFeatures
     )
   }
 
@@ -491,7 +491,7 @@ object Inputs {
     acceptFds: Boolean,
     forcedWorkspace: Option[os.Path],
     enableMarkdown: Boolean,
-    withRestrictedFeatures: Boolean
+    allowRestrictedFeatures: Boolean
   ): Either[BuildException, Inputs] = {
     val validatedArgs: Seq[Either[String, Seq[Element]]] =
       validateArgs(args, cwd, download, stdinOpt, acceptFds)
@@ -513,7 +513,7 @@ object Inputs {
         directories,
         forcedWorkspace,
         enableMarkdown,
-        withRestrictedFeatures
+        allowRestrictedFeatures
       ))
     }
     else
@@ -534,7 +534,7 @@ object Inputs {
     acceptFds: Boolean = false,
     forcedWorkspace: Option[os.Path] = None,
     enableMarkdown: Boolean = false,
-    withRestrictedFeatures: Boolean
+    allowRestrictedFeatures: Boolean
   ): Either[BuildException, Inputs] =
     if (
       args.isEmpty && scriptSnippetList.isEmpty && scalaSnippetList.isEmpty && javaSnippetList.isEmpty
@@ -556,7 +556,7 @@ object Inputs {
         acceptFds,
         forcedWorkspace,
         enableMarkdown,
-        withRestrictedFeatures
+        allowRestrictedFeatures
       )
 
   def default(): Option[Inputs] =
@@ -571,7 +571,7 @@ object Inputs {
       mayAppendHash = true,
       workspaceOrigin = None,
       enableMarkdown = enableMarkdown,
-      withRestrictedFeatures = false
+      allowRestrictedFeatures = false
     )
 
   def empty(projectName: String): Inputs =

diff --git a/modules/build/src/main/scala/scala/build/preprocessing/DataPreprocessor.scala b/modules/build/src/main/scala/scala/build/preprocessing/DataPreprocessor.scala
@@ -10,7 +10,7 @@ case object DataPreprocessor extends Preprocessor {
     input: Inputs.SingleElement,
     logger: Logger,
     maybeRecoverOnError: BuildException => Option[BuildException] = e => Some(e),
-    withRestrictedFeatures: Boolean
+    allowRestrictedFeatures: Boolean
   ): Option[Either[BuildException, Seq[PreprocessedSource]]] =
     input match {
       case file: Inputs.VirtualData =>

diff --git a/modules/build/src/main/scala/scala/build/preprocessing/DirectivesProcessor.scala b/modules/build/src/main/scala/scala/build/preprocessing/DirectivesProcessor.scala
@@ -26,15 +26,15 @@ object DirectivesProcessor {
     path: Either[String, os.Path],
     cwd: ScopePath,
     logger: Logger,
-    withRestrictedFeatures: Boolean
+    allowRestrictedFeatures: Boolean
   ): Either[BuildException, DirectivesProcessorOutput[T]] = {
     val configMonoidInstance = implicitly[ConfigMonoid[T]]
 
     def handleValues(handler: DirectiveHandler[T])(
       scopedDirective: ScopedDirective,
       logger: Logger
     ) =
-      if (withRestrictedFeatures && handler.isRestricted)
+      if (!allowRestrictedFeatures && handler.isRestricted)
         val msg =
           "This directive is not supported with 'scala' command. Please run it with `scala-cli` command or with `--power` flag."
         Left(DirectiveErrors(

diff --git a/modules/build/src/main/scala/scala/build/preprocessing/JavaPreprocessor.scala b/modules/build/src/main/scala/scala/build/preprocessing/JavaPreprocessor.scala
@@ -35,7 +35,7 @@ final case class JavaPreprocessor(
     input: Inputs.SingleElement,
     logger: Logger,
     maybeRecoverOnError: BuildException => Option[BuildException] = e => Some(e),
-    withRestrictedFeatures: Boolean
+    allowRestrictedFeatures: Boolean
   ): Option[Either[BuildException, Seq[PreprocessedSource]]] =
     input match {
       case j: Inputs.JavaFile => Some(either {
@@ -56,7 +56,7 @@ final case class JavaPreprocessor(
             Right(j.path),
             scopePath,
             logger,
-            withRestrictedFeatures
+            allowRestrictedFeatures
           ))
           Seq(PreprocessedSource.OnDisk(
             j.path,

diff --git a/modules/build/src/main/scala/scala/build/preprocessing/MarkdownPreprocessor.scala b/modules/build/src/main/scala/scala/build/preprocessing/MarkdownPreprocessor.scala
@@ -14,7 +14,7 @@ case object MarkdownPreprocessor extends Preprocessor {
     input: Inputs.SingleElement,
     logger: Logger,
     maybeRecoverOnError: BuildException => Option[BuildException],
-    withRestrictedFeatures: Boolean
+    allowRestrictedFeatures: Boolean
   ): Option[Either[BuildException, Seq[PreprocessedSource]]] =
     input match {
       case markdown: Inputs.MarkdownFile =>
@@ -28,7 +28,7 @@ case object MarkdownPreprocessor extends Preprocessor {
               ScopePath.fromPath(markdown.path),
               logger,
               maybeRecoverOnError,
-              withRestrictedFeatures
+              allowRestrictedFeatures
             )
           }
           preprocessed
@@ -46,7 +46,7 @@ case object MarkdownPreprocessor extends Preprocessor {
     scopePath: ScopePath,
     logger: Logger,
     maybeRecoverOnError: BuildException => Option[BuildException],
-    withRestrictedFeatures: Boolean
+    allowRestrictedFeatures: Boolean
   ): Either[BuildException, List[PreprocessedSource.InMemory]] = either {
     def preprocessSnippets(
       maybeCode: Option[String],
@@ -63,7 +63,7 @@ case object MarkdownPreprocessor extends Preprocessor {
                   scopeRoot = scopePath / os.up,
                   logger = logger,
                   maybeRecoverOnError = maybeRecoverOnError,
-                  withRestrictedFeatures = withRestrictedFeatures
+                  allowRestrictedFeatures = allowRestrictedFeatures
                 )
               }.getOrElse(ProcessingOutput(BuildRequirements(), Nil, BuildOptions(), None))
             val processedCode = processingOutput.updatedContent.getOrElse(code)

diff --git a/modules/build/src/main/scala/scala/build/preprocessing/Preprocessor.scala b/modules/build/src/main/scala/scala/build/preprocessing/Preprocessor.scala
@@ -8,6 +8,6 @@ trait Preprocessor {
     input: Inputs.SingleElement,
     logger: Logger,
     maybeRecoverOnError: BuildException => Option[BuildException] = e => Some(e),
-    withRestrictedFeatures: Boolean
+    allowRestrictedFeatures: Boolean
   ): Option[Either[BuildException, Seq[PreprocessedSource]]]
 }
diff --git a/modules/build/src/main/scala/scala/build/preprocessing/ScalaPreprocessor.scala b/modules/build/src/main/scala/scala/build/preprocessing/ScalaPreprocessor.scala
@@ -72,7 +72,7 @@ case object ScalaPreprocessor extends Preprocessor {
     input: Inputs.SingleElement,
     logger: Logger,
     maybeRecoverOnError: BuildException => Option[BuildException] = e => Some(e),
-    withRestrictedFeatures: Boolean
+    allowRestrictedFeatures: Boolean
   ): Option[Either[BuildException, Seq[PreprocessedSource]]] =
     input match {
       case f: Inputs.ScalaFile =>
@@ -87,7 +87,7 @@ case object ScalaPreprocessor extends Preprocessor {
                 scopePath / os.up,
                 logger,
                 maybeRecoverOnError,
-                withRestrictedFeatures
+                allowRestrictedFeatures
               )
             ) match {
               case None =>
@@ -137,7 +137,7 @@ case object ScalaPreprocessor extends Preprocessor {
                 v.scopePath / os.up,
                 logger,
                 maybeRecoverOnError,
-                withRestrictedFeatures
+                allowRestrictedFeatures
               )
             ).map {
               case ProcessingOutput(reqs, scopedReqs, opts, updatedContent) =>
@@ -168,7 +168,7 @@ case object ScalaPreprocessor extends Preprocessor {
     scopeRoot: ScopePath,
     logger: Logger,
     maybeRecoverOnError: BuildException => Option[BuildException],
-    withRestrictedFeatures: Boolean
+    allowRestrictedFeatures: Boolean
   ): Either[BuildException, Option[ProcessingOutput]] = either {
     val (content0, isSheBang) = SheBang.ignoreSheBangLines(content)
     val afterStrictUsing: StrictDirectivesProcessingOutput =
@@ -178,7 +178,7 @@ case object ScalaPreprocessor extends Preprocessor {
         scopeRoot,
         logger,
         maybeRecoverOnError,
-        withRestrictedFeatures
+        allowRestrictedFeatures
       ))
 
     val afterProcessImports: Option[SpecialImportsProcessingOutput] = value {
@@ -297,7 +297,7 @@ case object ScalaPreprocessor extends Preprocessor {
     cwd: ScopePath,
     logger: Logger,
     maybeRecoverOnError: BuildException => Option[BuildException] = e => Some(e),
-    withRestrictedFeatures: Boolean
+    allowRestrictedFeatures: Boolean
   ): Either[BuildException, StrictDirectivesProcessingOutput] = either {
     val contentChars = content.toCharArray
     val ExtractedDirectives(codeOffset, directives0) =
@@ -317,7 +317,7 @@ case object ScalaPreprocessor extends Preprocessor {
         path,
         cwd,
         logger,
-        withRestrictedFeatures
+        allowRestrictedFeatures
       )
     }
 
@@ -330,7 +330,7 @@ case object ScalaPreprocessor extends Preprocessor {
         path,
         cwd,
         logger,
-        withRestrictedFeatures
+        allowRestrictedFeatures
       )
     }
 

diff --git a/modules/build/src/main/scala/scala/build/preprocessing/ScriptPreprocessor.scala b/modules/build/src/main/scala/scala/build/preprocessing/ScriptPreprocessor.scala
@@ -14,7 +14,7 @@ final case class ScriptPreprocessor(codeWrapper: CodeWrapper) extends Preprocess
     input: Inputs.SingleElement,
     logger: Logger,
     maybeRecoverOnError: BuildException => Option[BuildException] = e => Some(e),
-    withRestrictedFeatures: Boolean
+    allowRestrictedFeatures: Boolean
   ): Option[Either[BuildException, Seq[PreprocessedSource]]] =
     input match {
       case script: Inputs.Script =>
@@ -29,7 +29,7 @@ final case class ScriptPreprocessor(codeWrapper: CodeWrapper) extends Preprocess
               ScopePath.fromPath(script.path),
               logger,
               maybeRecoverOnError,
-              withRestrictedFeatures
+              allowRestrictedFeatures
             )
           }
           preprocessed
@@ -49,7 +49,7 @@ final case class ScriptPreprocessor(codeWrapper: CodeWrapper) extends Preprocess
               script.scopePath,
               logger,
               maybeRecoverOnError,
-              withRestrictedFeatures
+              allowRestrictedFeatures
             )
           }
           preprocessed
@@ -71,7 +71,7 @@ object ScriptPreprocessor {
     scopePath: ScopePath,
     logger: Logger,
     maybeRecoverOnError: BuildException => Option[BuildException],
-    withRestrictedFeatures: Boolean
+    allowRestrictedFeatures: Boolean
   ): Either[BuildException, List[PreprocessedSource.InMemory]] = either {
 
     val (contentIgnoredSheBangLines, _) = SheBang.ignoreSheBangLines(content)
@@ -85,7 +85,7 @@ object ScriptPreprocessor {
         scopePath / os.up,
         logger,
         maybeRecoverOnError,
-        withRestrictedFeatures
+        allowRestrictedFeatures
       ))
         .getOrElse(ProcessingOutput(BuildRequirements(), Nil, BuildOptions(), None))
 

diff --git a/modules/build/src/test/scala/scala/build/tests/PreprocessingTests.scala b/modules/build/src/test/scala/scala/build/tests/PreprocessingTests.scala
@@ -12,7 +12,7 @@ class PreprocessingTests extends munit.FunSuite {
     val logger    = TestLogger()
     val scalaFile = Inputs.SourceScalaFile(os.temp.dir(), os.SubPath("NotExists.scala"))
 
-    val res = ScalaPreprocessor.preprocess(scalaFile, logger, withRestrictedFeatures = false)
+    val res = ScalaPreprocessor.preprocess(scalaFile, logger, allowRestrictedFeatures = false)
     val expectedMessage = s"File not found: ${scalaFile.path}"
 
     assert(res.nonEmpty)
@@ -27,7 +27,7 @@ class PreprocessingTests extends munit.FunSuite {
     val res = ScriptPreprocessor(CustomCodeWrapper).preprocess(
       scalaScript,
       logger,
-      withRestrictedFeatures = false
+      allowRestrictedFeatures = false
     )
     val expectedMessage = s"File not found: ${scalaScript.path}"
 
@@ -40,7 +40,7 @@ class PreprocessingTests extends munit.FunSuite {
     val logger       = TestLogger()
     val markdownFile = Inputs.MarkdownFile(os.temp.dir(), os.SubPath("NotExists.md"))
 
-    val res = MarkdownPreprocessor.preprocess(markdownFile, logger, withRestrictedFeatures = false)
+    val res = MarkdownPreprocessor.preprocess(markdownFile, logger, allowRestrictedFeatures = false)
     val expectedMessage = s"File not found: ${markdownFile.path}"
 
     assert(res.nonEmpty)

diff --git a/modules/build/src/test/scala/scala/build/tests/TestInputs.scala b/modules/build/src/test/scala/scala/build/tests/TestInputs.scala
@@ -43,7 +43,7 @@ final case class TestInputs(
         tmpDir,
         Directories.under(tmpDir / ".data"),
         forcedWorkspace = forcedWorkspaceOpt.map(_.resolveFrom(tmpDir)),
-        withRestrictedFeatures = false
+        allowRestrictedFeatures = true
       )
       res match {
         case Left(err)     => throw new Exception(err)

diff --git a/modules/cli-options/src/main/scala/scala/cli/commands/AboutOptions.scala b/modules/cli-options/src/main/scala/scala/cli/commands/AboutOptions.scala
@@ -11,6 +11,7 @@ final case class AboutOptions(
   @Recurse
     verbosity: VerbosityOptions = VerbosityOptions(),
   @Hidden
+  @HelpMessage(HelpMessages.passwordOption)
     ghToken: Option[PasswordOption] = None
 )
 // format: on

diff --git a/modules/cli-options/src/main/scala/scala/cli/commands/BenchmarkingOptions.scala b/modules/cli-options/src/main/scala/scala/cli/commands/BenchmarkingOptions.scala
@@ -5,10 +5,10 @@ import caseapp._
 // format: off
 final case class BenchmarkingOptions(
   @Group("Benchmarking")
-  @HelpMessage("Run JMH benchmarks")
+  @HelpMessage("[experimental] Run JMH benchmarks")
     jmh: Option[Boolean] = None,
   @Group("Benchmarking")
-  @HelpMessage("Set JMH version")
+  @HelpMessage("[experimental] Set JMH version")
   @ValueDescription("version")
     jmhVersion: Option[String] = None
 )

diff --git a/modules/cli-options/src/main/scala/scala/cli/commands/CompileCrossOptions.scala b/modules/cli-options/src/main/scala/scala/cli/commands/CompileCrossOptions.scala
diff --git a/modules/cli-options/src/main/scala/scala/cli/commands/CrossOptions.scala b/modules/cli-options/src/main/scala/scala/cli/commands/CrossOptions.scala
@@ -4,6 +4,7 @@ import caseapp._
 
 // format: off
 final case class CrossOptions(
+    @HelpMessage("[experimental] Run given command against all provided Scala versions and/or platforms")
     cross: Option[Boolean] = None
 )
 // format: on

diff --git a/modules/cli-options/src/main/scala/scala/cli/commands/DependencyUpdateOptions.scala b/modules/cli-options/src/main/scala/scala/cli/commands/DependencyUpdateOptions.scala
@@ -9,7 +9,7 @@ final case class DependencyUpdateOptions(
   @Recurse
     shared: SharedOptions = SharedOptions(),
   @Group("DependencyUpdate")
-  @HelpMessage("Update all dependency")
+  @HelpMessage("Update all dependencies if newer version was released")
     all: Boolean = false,
 )
   // format: on

diff --git a/modules/cli-options/src/main/scala/scala/cli/commands/DocOptions.scala b/modules/cli-options/src/main/scala/scala/cli/commands/DocOptions.scala
@@ -4,7 +4,7 @@ import caseapp._
 import caseapp.core.help.Help
 
 // format: off
-@HelpMessage("Generate Scaladoc documentation")
+@HelpMessage("Generate Scaladoc documentation", "By default, Scala CLI sets common scaladoc options and this mechanism can be disabled by using `--default-scaladoc-opts:false`.")
 final case class DocOptions(
   @Recurse
     shared: SharedOptions = SharedOptions(),
@@ -17,7 +17,7 @@ final case class DocOptions(
   @Name("f")
     force: Boolean = false,
   @Group("Doc")
-  @HelpMessage("Use default scaladoc options")
+  @HelpMessage("Control if scala CLI should use default options for scaladoc, true by default. Use `--default-scaladoc-opts:false` to not include default options.")
   @ExtraName("defaultScaladocOpts")
     defaultScaladocOptions: Option[Boolean] = None,
 )