docs: prioritize scala 3

[scarf005]

notable changes

• made the docs scala 3 oriented and moved scala 2 to notes
• removed the line

Note: If you’re using Scala 3 and your case class is defining default parameters, -Yretain-trees needs to be added to scalacOptions.

as it seemed to work fine without one in scala 3.

[CLAassistant]

All committers have signed the CLA.

[scarf005]

CI failure is due to actions/runner-images#10788

[987Nabil]

I am not sure about switching the focus to Scala 3. Also the retain trees was for sure needed the last time I tested it with Scala 3.3.x. If you have no PR, doc or added test that says otherwise, I do not want to remove it.

[scarf005]

I am not sure about switching the focus to Scala 3.

scala 3's derives syntax is significantly more concise compared to scala 2's implicit syntax. I thought it'd be worthwhile to showcase this feature first.

Also the retain trees was for sure needed the last time I tested it with Scala 3.3.x.

could you share your error log? it seemed to work when i tried following:

$ echo 'import zio.json.*

enum Fruit extends Product, Serializable derives JsonCodec:
  case Banana(curvature: Double) extends Fruit
  case Apple(poison: Boolean)    extends Fruit

export Fruit.*

@main def main() =
    val json1         = """{ "Banana":{ "curvature":0.5 }}"""
    val json2         = """{ "Apple": { "poison": false }}"""
    val malformedJson = """{ "Banana":{ "curvature": true }}"""

    println(json1.fromJson[Fruit])
    println(json2.fromJson[Fruit])
    println(malformedJson.fromJson[Fruit])

    println(List(Apple(false), Banana(0.4)).toJsonPretty)' > test.scala
$ scala -S 3.3.1 --dep dev.zio:zio-json_3:0.7.3 test.scala
Compiling project (Scala 3.3.1, JVM (23))
Compiled project (Scala 3.3.1, JVM (23))
Right(Banana(0.5))
Right(Apple(false))
Left(.Banana.curvature(expected a number, got t))
[
  {
    "Apple" : {
      "poison" : false
    }
  },
  {
    "Banana" : {
      "curvature" : 0.4
    }
  }
]

If you have no PR, doc or added test that says otherwise, I do not want to remove it.

I'd love to append mdoc:compile-only to scala 3 example, but stuck on mdoc work on scala 3 code. I'm not very good at sbt, so pointers would be appreciated!

I've tried following https://scalameta.org/mdoc/docs/installation.html#library but failed:

Details

diff --git a/build.sbt b/build.sbt
index 89a3a8e..536822a 100644
--- a/build.sbt
+++ b/build.sbt
@@ -387,7 +387,7 @@ lazy val docs = project
     zioJsonInteropScalaz7x.jvm
   )
   .settings(
-    crossScalaVersions -= ScalaDotty,
+    scalaVersion := ScalaDotty,
     moduleName := "zio-json-docs",
     scalacOptions += "-Ymacro-annotations",
     projectName := "ZIO JSON",
diff --git a/docs/index.md b/docs/index.md
index 57eb297..c5fefee 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -163,7 +163,7 @@ val res: Either[String, Fruit] = Right(Apple(false))
 
 Almost all of the standard library data types are supported as fields on the case class, and it is easy to add support if one is missing.
 
-```scala
+```scala mdoc:compile-only
 import zio.json.*
 
 enum Fruit extends Product, Serializable derives JsonCodec:
diff --git a/project/plugins.sbt b/project/plugins.sbt
index 20f4499..7f398b7 100644
--- a/project/plugins.sbt
+++ b/project/plugins.sbt
@@ -12,5 +12,6 @@ addSbtPlugin("pl.project13.scala" % "sbt-jcstress"                  % "0.2.0")
 addSbtPlugin("org.scoverage"      % "sbt-scoverage"                 % "2.0.11")
 addSbtPlugin("dev.zio"            % "zio-sbt-website"               % "0.4.0-alpha.28")
 addSbtPlugin("dev.zio"            % "zio-sbt-website"               % "0.4.0-alpha.27")
+addSbtPlugin("org.scalameta"      % "sbt-mdoc"                      % "2.6.2")
 
 libraryDependencies += "org.snakeyaml" % "snakeyaml-engine" % "2.8"

sbt compileDocs
[info] Compiling docs using mdoc ...
[error] Modules were resolved with conflicting cross-version suffixes in ProjectRef(uri("file:/run/media/home/scarf/repo/etc/one-time-contribution/zio-json/"), "docs"):
[error]    org.scala-lang.modules:scala-collection-compat _2.13, _3
[error] stack trace is suppressed; run last docs / update for the full output
[error] (docs / update) Conflicting cross-version suffixes in: org.scala-lang.modules:scala-collection-compat
[error] Total time: 2 s, completed 2025. 1. 5. 오후 11:52:56

then i tried running mdoc in CLI but that also failed with errors:

$ coursier launch org.scalameta:mdoc_3:2.6.2

...many more errors above

error: /run/media/home/scarf/repo/etc/one-time-contribution/zio-json/docs/interop/http4s.md:12:44: key not found: RELEASE_VERSION
  "dev.zio" % "zio-json-interop-http4s" % "@RELEASE_VERSION@"
                                           ^^^^^^^^^^^^^^^^^
error: /run/media/home/scarf/repo/etc/one-time-contribution/zio-json/docs/interop/refined.md:10:45: key not found: VERSION
  "dev.zio" % "zio-json-interop-refined" % "@VERSION@"
                                            ^^^^^^^^^
error: /run/media/home/scarf/repo/etc/one-time-contribution/zio-json/docs/interop/scalaz-7x.md:10:44: key not found: VERSION
  "dev.zio" % "zio-json-interop-scalaz" % "@VERSION@"
                                           ^^^^^^^^^
warning: interop/index.md:9:3: Unknown link 'interop/http4s.md'.
* [HTTP4s](http4s.md)
  ^^^^^^^^^^^^^^^^^^^

[987Nabil]

@scarf005 your example has no default values. retrain trees is only for default values

case class Bla(name: String = "A Default Value")

And there is no error, they are just not picked up by our macro

The issue with Scala 3 is, that a lot of ppl are still on Scala 2

[scarf005]

@scarf005 your example has no default values. retrain trees is only for default values

case class Bla(name: String = "A Default Value")

And there is no error, they are just not picked up by our macro

// test.scala
//> using scala 3.3.1
//> using dep dev.zio:zio-json_3:0.7.3

import zio.json.*

enum Fruit extends Product, Serializable derives JsonCodec:
  case Banana(curvature: Double = 3.0) extends Fruit
  case Apple(poison: Boolean = false)    extends Fruit

export Fruit.*

case class Bla(name: String = "A Default Value") derives JsonCodec

@main def main() =
    val json1         = """{ "Banana": { }}"""
    val json2         = """{ "Apple": {} }"""
    val malformedJson = """{ "Banana": { "curvature": true }}"""

    println(json1.fromJson[Fruit])
    println(json2.fromJson[Fruit])
    println(malformedJson.fromJson[Fruit])

    println(List(Apple(false), Banana(0.4)).toJsonPretty)

    val blaJson = """{ "name": "A New Value" }"""
    val blaEmptyJson = """{}"""

    println(blaJson.fromJson[Bla])
    println(blaEmptyJson.fromJson[Bla])
    println(Bla().toJsonPretty)
    println(Bla("A New Value").toJsonPretty)

$ scala test.scala
Compiling project (Scala 3.3.1, JVM (23))
Compiled project (Scala 3.3.1, JVM (23))
Right(Banana(3.0))
Right(Apple(false))
Left(.Banana.curvature(expected a number, got t))
[
  {
    "Apple" : {
      "poison" : false
    }
  },
  {
    "Banana" : {
      "curvature" : 0.4
    }
  }
]
Right(Bla(A New Value))
Right(Bla(A Default Value))
{
  "name" : "A Default Value"
}
{
  "name" : "A New Value"
}

Default values seem to work without the need for retrain trees, unless I’m missing something.

The issue with Scala 3 is, that a lot of ppl are still on Scala 2

But this PR doesn’t remove or hide Scala 2 snippets; it merely prioritizes Scala 3 snippets.
Given that 49% of Scala users were already using Scala 3 in 2023, it doesn’t seem justified to prioritize a legacy version.