Use 'enumeration' to clearly name true enums

softwaremill · Sep 28, 2023 · 33be891 · 33be891
1 parent d03421a
commit 33be891
Show file tree

Hide file tree

Showing 6 changed files with 20 additions and 56 deletions.
diff --git a/core/src/main/scala-3/sttp/tapir/internal/EnumMacros.scala b/core/src/main/scala-3/sttp/tapir/internal/EnumMacros.scala
diff --git a/core/src/main/scala-3/sttp/tapir/macros/ValidatorMacros.scala b/core/src/main/scala-3/sttp/tapir/macros/ValidatorMacros.scala
@@ -1,6 +1,6 @@
 package sttp.tapir.macros
 
-import sttp.tapir.internal.EnumMacros.*
+import sttp.tapir.internal.EnumerationMacros.*
 import sttp.tapir.Validator
 import sttp.tapir.Schema
 

diff --git a/doc/contributing.md b/doc/contributing.md
@@ -2,13 +2,22 @@
 
 All suggestions welcome :)!
 
-If you'd like to contribute, see the list of [issues](https://github.com/softwaremill/tapir/issues) and pick one! 
+If you'd like to contribute, see the list of [issues](https://github.com/softwaremill/tapir/issues) and pick one!
 Or report your own. If you have an idea you'd like to discuss, that's always a good option.
 
-If you are having doubts on the *why* or *how* something works, don't hesitate to ask a question on
-[discourse](https://softwaremill.community/c/tapir) or via github. This probably means that the documentation, scaladocs or 
+If you are having doubts on the _why_ or _how_ something works, don't hesitate to ask a question on
+[discourse](https://softwaremill.community/c/tapir) or via github. This probably means that the documentation, scaladocs or
 code is unclear and can be improved for the benefit of all.
 
+## Conventions
+
+### Enumerations
+
+Scala 3 introduces `enum`, which can be used to represent sealed hierarchies with simpler syntax, or actual "true" enumerations,
+that is parameterless enums or sealed traits with only case objects as children. Tapir needs to treat the latter differently,
+in order to allow using OpenAPI `enum` elements and derive JSON codecs which represent them as simple values (without discriminator).
+Let's use the name `enumeration` in Tapir codebase to represent these "true" enumerations and avoid ambiguity.
+
 ## Acknowledgments
 
 Tuple-concatenating code is copied from [akka-http](https://github.com/akka/akka-http/blob/master/akka-http/src/main/scala/akka/http/scaladsl/server/util/TupleOps.scala)
@@ -17,4 +26,4 @@ Parts of generic derivation configuration is copied from [circe](https://github.
 
 Implementation of mirror for union and intersection types are originally implemented by [Iltotore](https://github.com/Iltotore) in [this gist](https://gist.github.com/Iltotore/eece20188d383f7aee16a0b89eeb887f)
 
-Tapir logo & stickers have been drawn by [impurepics](https://twitter.com/impurepics).
+Tapir logo & stickers have been drawn by [impurepics](https://twitter.com/impurepics).
diff --git a/json/pickler/src/main/scala/sttp/tapir/json/pickler/Pickler.scala b/json/pickler/src/main/scala/sttp/tapir/json/pickler/Pickler.scala
@@ -1,6 +1,6 @@
 package sttp.tapir.json.pickler
 
-import sttp.tapir.internal.EnumMacros.*
+import sttp.tapir.internal.EnumerationMacros.*
 import sttp.tapir.Codec.JsonCodec
 import sttp.tapir.DecodeResult.Error.JsonDecodeException
 import sttp.tapir.DecodeResult.{Error, Value}
@@ -69,7 +69,7 @@ object Pickler:
               s"Unexpected product type (case class) ${implicitly[ClassTag[T]].runtimeClass.getSimpleName()}, this method should only be used with sum types (like sealed hierarchy)"
             )
           case _: Mirror.SumOf[T] =>
-            inline if (isScalaEnum[T])
+            inline if (isEnumeration[T])
               error("oneOfUsingField cannot be used with enums. Try Pickler.derivedEnumeration instead.")
             else {
               given schemaV: Schema[V] = discriminatorPickler.schema
@@ -278,7 +278,7 @@ object Pickler:
       case p: Mirror.ProductOf[T] => picklerProduct(p, childPicklers)
       case _: Mirror.SumOf[T] =>
         val schema: Schema[T] =
-          inline if (isScalaEnum[T])
+          inline if (isEnumeration[T])
             Schema.derivedEnumeration[T].defaultStringBased
           else
             Schema.derived[T]

diff --git a/json/pickler/src/main/scala/sttp/tapir/json/pickler/Writers.scala b/json/pickler/src/main/scala/sttp/tapir/json/pickler/Writers.scala
@@ -3,7 +3,7 @@ package sttp.tapir.json.pickler
 import _root_.upickle.core.Annotator.Checker
 import _root_.upickle.core.{ObjVisitor, Visitor, _}
 import _root_.upickle.implicits.{WritersVersionSpecific, macros => upickleMacros}
-import sttp.tapir.internal.EnumMacros.*
+import sttp.tapir.internal.EnumerationMacros.*
 import sttp.tapir.Schema
 import sttp.tapir.SchemaType.SProduct
 import sttp.tapir.generic.Configuration
@@ -65,7 +65,7 @@ private[pickler] trait Writers extends WritersVersionSpecific with UpickleHelper
         )
     }
 
-    inline if upickleMacros.isMemberOfSealedHierarchy[T] && !isScalaEnum[T] then
+    inline if upickleMacros.isMemberOfSealedHierarchy[T] && !isEnumeration[T] then
       annotate[T](
         writer,
         upickleMacros.tagName[T],

diff --git a/json/pickler/src/main/scala/sttp/tapir/json/pickler/macros.scala b/json/pickler/src/main/scala/sttp/tapir/json/pickler/macros.scala
@@ -2,7 +2,7 @@ package sttp.tapir.json.pickler
 
 import _root_.upickle.implicits.*
 import _root_.upickle.implicits.{macros => uMacros}
-import sttp.tapir.internal.EnumMacros.*
+import sttp.tapir.internal.EnumerationMacros.*
 import sttp.tapir.SchemaType
 import sttp.tapir.SchemaType.SProduct
 
@@ -92,4 +92,3 @@ private[pickler] object macros:
 
     Expr.block(statements, '{})
   }
-