Scaladoc experimentals page overview

[BarkingBad]

The brief idea is to automatically gather all the @experimental annotated constructs and list them on the dedicated page so it will be easy to navigate to them.

Do we want to link some static docs to them explaining them or something similar?

[odersky]

I am not sure this is necessary. We can leave the experimental things in place. First, there are not that many. Second, the regular doc pages is where people would look for them. Third, they are already clearly marked.

But what we do need is this: We need to a link for every language feature that is controlled by an experimental language import. Right now, these doc pages exist, but are not linked from anywhere. We need something like https://doc.rust-lang.org/beta/unstable-book/the-unstable-book.html to change that. Since we only have a handful of experimental features right now, we can just have an entry in https://dotty.epfl.ch/docs/Reference/index.html titled "Experimental Features" that links to a page explaining that these are experimental features available only in unstable compilers. And then that page could have an index pointing to the individual feature doc pages.

So this work should concentrate on organizing the doc pages, not inventing new technical schemes.

[romanowski]

@julienrf moved the content of Reference to docs.scala-lang.org so at this moment we do not have a way to generate content in the Reference page automatically, so it is aligned and taken from doctags. This is jus a temporal solution so we can think how to address that in future.

For now, we can create such entry in the Reference page within docs and the question is whether we need some kind of mechanism to generate or validate such page automatically. If we want experimental to be used outside the compiler I think we should such a feature to scaladoc but if we want to use it only within the compiler I think we can live without or really rudimentary checks.

[julienrf]

I agree that we should simply create a new "chapter" in the Scala reference. You can do it now on the docs.scala-lang repo, or wait for the solution to publish the content of the docs of the dotty repo into the docs.scala-lang repo.