search

scala / scala3

The Scala 3 compiler, also known as Dotty.
https://dotty.epfl.ch
Apache License 2.0
5.88k stars 1.06k forks source link

No documentation for `-scastie-configuration` #16220

Closed ckipp01 closed 1 year ago

ckipp01 commented 2 years ago

Compiler version

All of them

Example

As outlined in here most users of Scaladoc are going to want to use examples of their code. However, by default the integration with scastie won't work for this since it won't recognize any of the needed dependencies, including your own code. From the response there and in the pr that added this here you see the following:

You can there specify libraryDependencies setting. It will probably be done better in future (automatically get this configuration from sbt) but for now it works like that.

However there is no further explanation on how to actually use -scastie-configuration and even looking in the code you just see it's a String setting with a description and no examples of how to actually use it.

Expectation

I'd expect for a core feature like this to be documented so that library authors can use Scaladoc with the scastie integration for their projects. Right now it's pretty unusable for snippets.

SethTisue commented 2 years ago

Right now it's pretty unusable for snippets

And what I'm sometimes seeing in the wild is people publishing Scaladoc that has snippets, but they don't actually run. I'm not sure the library maintainers are even noticing the play buttons.

I doubt it's a good idea for the Scastie links to be emitted to be default. As Chris wrote in the discussion,

I also then don't see a way to turn the play button off

szymon-rd commented 2 years ago

Thanks for reporting! We will look into it after the current polishing of scaladoc.