Skip to content

Scaladoc: Fix problems with documenting scala.js projects #12364

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 10, 2021
Merged

Scaladoc: Fix problems with documenting scala.js projects #12364

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions compiler/src/dotty/tools/dotc/config/ScalaSettings.scala
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,7 @@ trait CommonScalaSettings { self: Settings.SettingGroup =>
/** Other settings */
val encoding: Setting[String] = StringSetting("-encoding", "encoding", "Specify character encoding used by source files.", Properties.sourceEncoding, aliases = List("--encoding"))
val usejavacp: Setting[Boolean] = BooleanSetting("-usejavacp", "Utilize the java.class.path in classpath resolution.", aliases = List("--use-java-class-path"))
val scalajs: Setting[Boolean] = BooleanSetting("-scalajs", "Compile in Scala.js mode (requires scalajs-library.jar on the classpath).", aliases = List("--scalajs"))

/** Plugin-related setting */
val plugin: Setting[List[String]] = MultiStringSetting ("-Xplugin", "paths", "Load a plugin from each classpath.")
Expand All @@ -54,7 +55,7 @@ trait CommonScalaSettings { self: Settings.SettingGroup =>
val pluginOptions: Setting[List[String]] = MultiStringSetting ("-P", "plugin:opt", "Pass an option to a plugin, e.g. -P:<plugin>:<opt>")
}

class ScalaSettings extends Settings.SettingGroup with CommonScalaSettings {
trait AllScalaSettings extends CommonScalaSettings { self: Settings.SettingGroup =>
// Keep synchronized with `classfileVersion` in `BCodeIdiomatic`
private val minTargetVersion = 8
private val maxTargetVersion = 17
Expand All @@ -80,7 +81,6 @@ class ScalaSettings extends Settings.SettingGroup with CommonScalaSettings {
val feature: Setting[Boolean] = BooleanSetting("-feature", "Emit warning and location for usages of features that should be imported explicitly.", aliases = List("--feature"))
val release: Setting[String] = ChoiceSetting("-release", "release", "Compile code with classes specific to the given version of the Java platform available on the classpath and emit bytecode for this version.", supportedReleaseVersions, "", aliases = List("--release"))
val source: Setting[String] = ChoiceSetting("-source", "source version", "source version", List("3.0", "future", "3.0-migration", "future-migration"), "3.0", aliases = List("--source"))
val scalajs: Setting[Boolean] = BooleanSetting("-scalajs", "Compile in Scala.js mode (requires scalajs-library.jar on the classpath).", aliases = List("--scalajs"))
val unchecked: Setting[Boolean] = BooleanSetting("-unchecked", "Enable additional warnings where generated code depends on assumptions.", aliases = List("--unchecked"))
val uniqid: Setting[Boolean] = BooleanSetting("-uniqid", "Uniquely tag all identifiers in debugging output.", aliases = List("--unique-id"))
val language: Setting[List[String]] = MultiStringSetting("-language", "feature", "Enable one or more language features.", aliases = List("--language"))
Expand Down Expand Up @@ -225,3 +225,5 @@ class ScalaSettings extends Settings.SettingGroup with CommonScalaSettings {

val wikiSyntax: Setting[Boolean] = BooleanSetting("-Xwiki-syntax", "Retains the Scala2 behavior of using Wiki Syntax in Scaladoc.")
}

class ScalaSettings extends Settings.SettingGroup with AllScalaSettings
3 changes: 3 additions & 0 deletions scaladoc/src/dotty/tools/scaladoc/DocContext.scala
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,9 @@ extension (r: report.type)
def warn(m: String, e: Throwable)(using CompilerContext): Unit =
r.warning(s"$m: ${throwableToString(e)}")

def echo(m: String)(using CompilerContext): Unit =
r.echo(m)

case class NavigationNode(name: String, dri: DRI, nested: Seq[NavigationNode])

case class DocContext(args: Scaladoc.Args, compilerContext: CompilerContext):
Expand Down
12 changes: 10 additions & 2 deletions scaladoc/src/dotty/tools/scaladoc/Scaladoc.scala
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ import collection.immutable.ArraySeq
import java.nio.file.Files

import dotty.tools.dotc.config.Settings._
import dotty.tools.dotc.config.CommonScalaSettings
import dotty.tools.dotc.config.{ CommonScalaSettings, AllScalaSettings }
import dotty.tools.dotc.reporting.Reporter
import dotty.tools.dotc.core.Contexts._

Expand Down Expand Up @@ -100,7 +100,15 @@ object Scaladoc:
}

val commonScalaSettings = (new SettingGroup with CommonScalaSettings).allSettings
allSettings.filter(commonScalaSettings.contains).foreach(setInGlobal)
val allScalaSettings = (new SettingGroup with AllScalaSettings).allSettings

val (shared, other) = allSettings
.filter(s => !s.isDefaultIn(summary.sstate))
.filter(allScalaSettings.contains)
.partition(commonScalaSettings.contains)
shared.foreach(setInGlobal)

if !other.isEmpty then report.echo(s"Skipping unused scalacOptions: ${other.map(_.name).mkString(", ")}")
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If sbt automatically passes these options to scaladoc, then we shouldn't display this message to the user since they can't do anything about it, so it would just be noise.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I thought that it's nice to inform (instead of warn) an user that these options were passed to scaladoc but are unused. Doing it silentely might be confusing when someone adds compile options by:

Compile / doc / scalacOptions ++= ...

And won't know why they are not working. What do you think?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we could distinguish which options were user-defined and which were just copied from Compile / scalacOptions that would be nice indeed, but as it is I'm not sure.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should print this message using the info or debug level since in most cases this will be noise but in few rare cases, this may save quite a lot of debugging.


def parseTastyRoots(roots: String) =
roots.split(File.pathSeparatorChar).toList.map(new File(_))
Expand Down
4 changes: 2 additions & 2 deletions scaladoc/src/dotty/tools/scaladoc/ScaladocSettings.scala
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,14 +9,14 @@ import collection.immutable.ArraySeq
import java.nio.file.Files

import dotty.tools.dotc.config.Settings._
import dotty.tools.dotc.config.CommonScalaSettings
import dotty.tools.dotc.config.AllScalaSettings
import dotty.tools.scaladoc.Scaladoc._
import dotty.tools.dotc.config.Settings.Setting.value
import dotty.tools.dotc.config.Properties._
import dotty.tools.dotc.config.CliCommand
import dotty.tools.dotc.core.Contexts._

class ScaladocSettings extends SettingGroup with CommonScalaSettings:
class ScaladocSettings extends SettingGroup with AllScalaSettings:
val unsupportedSettings = Seq(
// Options that we like to support
bootclasspath, extdirs, javabootclasspath, encoding, usejavacp,
Expand Down