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)

[SethTisue]

@gavinbaumanis interested in returning to this?

[gavinbaumanis]

I am returning to this now. Thanks @SethTisue.

[gavinbaumanis]

@SethTisue : Do you want a giant issue / document at the end of this - or do you want individual issues raised for the things that I find?
I don't mind either way.

[SethTisue]

uh, I guess a single issue for now, and then I suppose we might choose later to split things out

[gavinbaumanis]

@SethTisue : OK so I am editing the code to correct the documentation (I am happy to go through it and see if I can do it) - Or am I just flagging the issues I have found between the two different flavours (*.YML and the docs)?
Thanks!

[SethTisue]

@gavinbaumanis the ambition level is up to you — any amount of improvement is better than nothing. Is the automatic generation aspect even currently working? If not, that seems like the single most important thing to address.

[gavinbaumanis]

@SethTisue : I am happy to try it all! : Though, I have had a look at the code and it is beyond me at the moment to fix without context / help. Do you know anyone who knows about the document generation engine - that I could ask directly - at the times I get stuck? Thanks.

[SethTisue]

Do you know anyone who knows about the document generation engine

I believe @exoego is the original author. @som-snytt and I can try to help as well. Usually the best way to get help is to open a draft PR in scala/scala and ask for it there. Chat rooms are catch-as-catch-can, but asking things on https://gitter.im/scala/contributors definitely works at least some of the time.

[SethTisue]

Is there a new volunteer who would like to tackle this?

[Shorla]

Hi @SethTisue, I don't mind getting started on this.

[Shorla]

How can I get started on it?

[SethTisue]

@Shorla are you able to run generateDocsData?

[Shorla]

@SethTissue I tried running it with docs/mdoc, it said commamd not found.
How do I run it?

[som-snytt]

Responding to an old comment about -target, -target and -release are normalized in a recent PR. They accept the jvm-1.8 style values for compatibility only. Should the doc page show all aliases for options and values? I'd suggest a separate curated page to show variants, which may be ad-hoc. Also, -release has upper limit that is the spec version of the running JVM, so some care is required when generating doc automatically. I'm not sure automation is still a goal.

[som-snytt]

The PR for optimizer flags has landed, so at least there is no need to republish the options page.

But that would be another example of a canonical form with variants (which may or may not be deprecated).

@Shorla there is a "task" under sbt in the scala/scala build. I think it was mentioned in the long thread above. Ideal case is just to run it and ... does it update the file in this sibling repo? Something like that.

[som-snytt]

Is there a new volunteer?

Old volunteers also welcome. The Scala project is not "newist".

[SethTisue]

How do I run it?

clone the scala/scala repo, then start sbt, then enter generateDocsData

there's a little bit of code for it in build.sbt, and then the main part of the code is in project/GenerateDocsData.scala

[som-snytt]

Another idea at scala/scala3#15406 (comment) is to automate help doc for options.

Maybe a widget to reveal per-option help. That would let you add an option, add help text, and not touch markdown.

-opt has a dedicated page; it wouldn't be terrible to link to it directly, but not sure where to provide the link.

[SethTisue]

Should the doc page show all aliases for options and values?

I think so, yes. Visually deemphasized, but present so they show up in searches (whether via Google, or when searching within the page).