Scala 2 compiler options page needs updating

[gavinbaumanis]

https://docs.scala-lang.org/overviews/compiler-options/index.html
mentions;
-optimize or -optimise Enables optimizations.

This option is now deprecated.
(probably need to check all others, too.)

[gavinbaumanis]

I'm actually happy to help with this.

Without "actually" knowing, I can use each of the options in turns and see if they give any deprecation warnings.

But how shall I update the docs?

• Just add a "Deprecated" label of sorts?

Also "I" am not going to know if there are any available options that are currently missing from the page, without some help to where I might find an authoritative list.

[SethTisue]

@gavinbaumanis thanks for taking an interest in this!

over in the scala/scala repo, running sbt followed by generateDocsData generates a compiler-options.yml file, and then the web page is generated from that

I think that's probably the key piece of information you were missing in order to dig deeper into this...?

[gavinbaumanis]

@SethTisue : Awesome - thanks very much!

[gavinbaumanis]

In the -opt section of compiler-options.yml is the following;

- choice: "l:project"
        description: "[deprecated, use -opt:l:inline, -opt-inline-from] Enable cross-method optimizations within the current project."
      - choice: "l:classpath"
        description: "[deprecated, use -opt:l:inline, -opt-inline-from] Enable cross-method optimizations across the entire classpath."

They DO NOT appear in the page;
https://docs.scala-lang.org/overviews/compiler-options/index.html

Is the [deprecated text in the YML automatically handled?
Could we use this same string to flag other deprecated directives - to be left off the page?
Or are these 2 options manually removed - after the fact?

[gavinbaumanis]

Also, please, I have found a discrepancy between the YML and the documentation page;
The YML has for the "-target" directive, choices in the form;
jvm-1.5 through to jvm-1.8

But the documentation page has;
-target:8 . through to -target:12

Not only is the text different, but the JVM values don't line-up either.
Is one actually wrong?

Do I flag these differences too - while I am looking for deprecated values?
(And do I do that here - or should they have their own issue?)
Thanks!

[SethTisue]

Is the [deprecated text in the YML automatically handled?

I don't know. You might need to look at the code that processes compiler-options.yml

Or are these 2 options manually removed - after the fact?

I don't know. I certainly hope we aren't manually altering things. We shouldn't be, having it be automatic is the only sustainable approach.

(re -target:8 vs -target:jvm-1.8)
Is one actually wrong?

it appears to me from https://github.com/scala/scala/blob/2.13.x/src/compiler/scala/tools/nsc/settings/StandardScalaSettings.scala#L58-L64 that -target:8 is the standard form and the other form is legacy that we needn't document

Do I flag these differences too - while I am looking for deprecated values?
(And do I do that here - or should they have their own issue?)

I would say the ambition level here is up to you — any amount of forward progress on this that you make is good. The more accurate the page gets the better, but as they say, the perfect is the enemy of the good.

(If you end up with some undone work, an additional ticket with a list would be welcome; perhaps someone else would choose to tackle it.)

[gavinbaumanis]

@SethTisue : Thanks Seth.
I am happy to go through all the options (that I can) and;

• Document the differences between the documentation and the YML.
• I'll also look in to the source and see if I can root out the mechanics for the creation of the documentation page
• Create a PR for all that I find.

[gavinbaumanis]

@SethTisue
In scala/src/compiler/scala/tools/nsc/settings/ScalaSettings.scala
@ line 497 is the following;

val optimise      = BooleanSetting("-optimize", "Enables optimizations.")
    .withAbbreviation("-optimise")
    .withDeprecationMessage("Since 2.12, enables -opt:l:inline -opt-inline-from:**. See -opt:help.")
    .withPostSetHook(_ => {
      opt.enable(optChoices.lInline)
      optInlineFrom.value = List("**")
    })

Which would seem to be saying that it should produce the documentation of;

-optimize is deprecated: Since 2.12, enables -opt:l:inline -opt-inline-from:**. See -opt:help.

Which it does do for sbt.

However the documentation;
Only has the text;

Enables optimizations.

In /scala/project/GenerateDocsData.scala @ 66 is;```
def mergeChoice(labels: Seq[String], descriptions: Seq[String]): Seq[Choice] =
labels.zipAll(descriptions, "", "").map {
case (choice, d) => Choice(
choice,
description = Option(d).map(markdownifyBackquote).map(dehtmlfy).filter(.nonEmpty),
// FIXME
deprecated = Some("EXPLAIN_ALTERNATIVE").filter( => d.toLowerCase.contains("deprecated"))
)
}

and, @91 ... is;
```def option(s: Setting): ScalacOption =
    ScalacOption(
      option = s.name,
      schema = schema(s),
      description = dehtmlfy(markdownifyBackquote(s.helpDescription)),
      abbreviations = s.abbreviations,
      //TODO
      deprecated = Some("EXPLAIN_ALTERNATIVE").filter(_ => s.helpDescription.toLowerCase.contains("deprecated"))
    )

If I am reading this correctly - I THINK the deprecation warning is missing from the HTML docs because the word "deprecated" is NOT is the description : and test used in the compiler / sbt is supplied via;
.withDeprecationMessage("Since 2.12, enables -opt:l:inline -opt-inline-from:**. See -opt:help.") from scala/src/compiler/scala/tools/nsc/settings/ScalaSettings.scala

Do I have this right / am I missing something?
(I note the TODO / FIXME comments - so perhaps "I" am wasting my time at the moment?)

And; is there a way I can locally produce the documentation for testing locally?

Thanks.

[SethTisue]

Do I have this right / am I missing something?

I haven't seen this code before, but your reasoning seems plausible to me.

I'm pretty sure nobody is working on any TODOs or FIXMEs in this area, it hasn't been touched in a while.

I'll @-mention @exoego in case he wants to add anything.

is there a way I can locally produce the documentation for testing locally?

in the scala/scala repo, build.sbt has:

    // ../docs.scala-lang/_data/compiler-options.yml
    commands += Command.command("generateDocsData") { state =>
      val dir = (((baseDirectory in ThisBuild).value) / ".." / "docs.scala-lang" / "_data")
      val target = if (dir.exists) dir else ((baseDirectory in ThisBuild).value)
      GenerateDocsData.run(target.getAbsoluteFile)
      state
    },

so running sbt then doing generateDocsData should do it

[SethTisue]

relevant ticket I happened across: scala/bug#11642

it seems to indicate that perhaps the generateDocsData task doesn't work at all on 2.13 (as in, seems to work, but is actually using the 2.12 compiler flags info) — does what you're seeing confirm or contradict that?

[som-snytt]

Yes, the tool was supposed to make yml reflect scalac -help, -X, -Y, -V, -W.

Another bug in flight is scala/bug#11873 to optimise the optimiser groups.

[SethTisue]

@gavinbaumanis interested in returning to this...?

[som-snytt]

Someone asked on SO how do I see options for 2.11? It would nice to have a fancy drop-down.

[SethTisue]

(a low-tech solution could be to add a section to the current version that links to the source on GitHub for the last 2.11.x and 2.12.x versions that existed. or even link to Wayback Machine versions)