diff --git a/zio-schema/shared/src/main/scala/zio/schema/annotation/caseName.scala b/zio-schema/shared/src/main/scala/zio/schema/annotation/caseName.scala index 326f32775..4fd8a7833 100644 --- a/zio-schema/shared/src/main/scala/zio/schema/annotation/caseName.scala +++ b/zio-schema/shared/src/main/scala/zio/schema/annotation/caseName.scala @@ -2,4 +2,12 @@ package zio.schema.annotation import scala.annotation.StaticAnnotation +/** + * Annotation for specifying an alternate identity for a case of an enum. + * Currently, the subtype name is always used. + * + * This is the dual of `@fieldName`, but for sums rather than products. + * + * @param name The alternate name to use for the case. + */ final case class caseName(name: String) extends StaticAnnotation diff --git a/zio-schema/shared/src/main/scala/zio/schema/annotation/caseNameAliases.scala b/zio-schema/shared/src/main/scala/zio/schema/annotation/caseNameAliases.scala index 8b438a8d2..6167a3946 100644 --- a/zio-schema/shared/src/main/scala/zio/schema/annotation/caseNameAliases.scala +++ b/zio-schema/shared/src/main/scala/zio/schema/annotation/caseNameAliases.scala @@ -1,3 +1,8 @@ package zio.schema.annotation +/** + * Annotation for specifying a list of aliases if the case name is somehow known by. + * + * @param aliases A variable-length sequence of Strings representing the aliases of the case. + */ final case class caseNameAliases(aliases: String*) extends scala.annotation.StaticAnnotation diff --git a/zio-schema/shared/src/main/scala/zio/schema/annotation/discriminatorName.scala b/zio-schema/shared/src/main/scala/zio/schema/annotation/discriminatorName.scala index a3b055204..80d61a1d5 100644 --- a/zio-schema/shared/src/main/scala/zio/schema/annotation/discriminatorName.scala +++ b/zio-schema/shared/src/main/scala/zio/schema/annotation/discriminatorName.scala @@ -1,3 +1,12 @@ package zio.schema.annotation +/** + * Annotation used to specify the name of a field that will be used to contain the id which identifies + * which term in an enum is being serialized / deserialized. + * + * For example, if you set `@discriminatorName("type")`, then a field called "type" will be used to store + * the identity of the case of the enum that is being serialized / deserialized. + * + * @param tag the name of the field that will be used to store the identity of the case of the enum + */ final case class discriminatorName(tag: String) extends scala.annotation.StaticAnnotation diff --git a/zio-schema/shared/src/main/scala/zio/schema/annotation/fieldDefaultValue.scala b/zio-schema/shared/src/main/scala/zio/schema/annotation/fieldDefaultValue.scala index 9f6d2550e..1129fac08 100644 --- a/zio-schema/shared/src/main/scala/zio/schema/annotation/fieldDefaultValue.scala +++ b/zio-schema/shared/src/main/scala/zio/schema/annotation/fieldDefaultValue.scala @@ -1,3 +1,10 @@ package zio.schema.annotation +/** + * Annotation specifying the default value that should be utilized when the field + * is not present during deserialization. This is similar to `@optionalField`, + * except that the default value is user-defined rather than computed automatically using the field schema. + * + * @param value The default value to use for the field. + */ final case class fieldDefaultValue[A](value: A) extends scala.annotation.StaticAnnotation diff --git a/zio-schema/shared/src/main/scala/zio/schema/annotation/fieldName.scala b/zio-schema/shared/src/main/scala/zio/schema/annotation/fieldName.scala index 48be72fee..14ab8cf16 100644 --- a/zio-schema/shared/src/main/scala/zio/schema/annotation/fieldName.scala +++ b/zio-schema/shared/src/main/scala/zio/schema/annotation/fieldName.scala @@ -1,3 +1,13 @@ package zio.schema.annotation +/** + * Annotation for specifying an alternate identity for a field of a case class. + * Currently, the field name is always used. But sometimes, it can be convenient to have control over that name. + * + * For example, the API expects username to be stored as user_name, but inside the case class, + * the field is named username. Such an annotation, applied directly to the field, + * could indicate a different identity for the field than the field name itself. + * + * @param name The alternate name to use for the field. + */ final case class fieldName(name: String) extends scala.annotation.StaticAnnotation diff --git a/zio-schema/shared/src/main/scala/zio/schema/annotation/fieldNameAliases.scala b/zio-schema/shared/src/main/scala/zio/schema/annotation/fieldNameAliases.scala index f94891fb2..8fa5b6d86 100644 --- a/zio-schema/shared/src/main/scala/zio/schema/annotation/fieldNameAliases.scala +++ b/zio-schema/shared/src/main/scala/zio/schema/annotation/fieldNameAliases.scala @@ -1,3 +1,8 @@ package zio.schema.annotation +/** + * Annotation for specifying a list of aliases if the field is somehow known by. + * + * @param aliases A variable-length sequence of Strings representing the aliases of the field. + */ final case class fieldNameAliases(aliases: String*) extends scala.annotation.StaticAnnotation diff --git a/zio-schema/shared/src/main/scala/zio/schema/annotation/optionalField.scala b/zio-schema/shared/src/main/scala/zio/schema/annotation/optionalField.scala index a32315d77..d3c4568f1 100644 --- a/zio-schema/shared/src/main/scala/zio/schema/annotation/optionalField.scala +++ b/zio-schema/shared/src/main/scala/zio/schema/annotation/optionalField.scala @@ -1,3 +1,6 @@ package zio.schema.annotation +/** + * Annotation specifying that deserialization should not fail even if a value of this type is not specified. + */ final case class optionalField() extends scala.annotation.StaticAnnotation diff --git a/zio-schema/shared/src/main/scala/zio/schema/annotation/recordName.scala b/zio-schema/shared/src/main/scala/zio/schema/annotation/recordName.scala index 69be3f2a9..a3c3b3ec9 100644 --- a/zio-schema/shared/src/main/scala/zio/schema/annotation/recordName.scala +++ b/zio-schema/shared/src/main/scala/zio/schema/annotation/recordName.scala @@ -2,4 +2,9 @@ package zio.schema.annotation import scala.annotation.StaticAnnotation +/** + * Annotation for specifying an alternate name for a record. + * + * @param name The alternate name to use for the record. + */ final case class recordName(name: String) extends StaticAnnotation diff --git a/zio-schema/shared/src/main/scala/zio/schema/annotation/rejectExtraFields.scala b/zio-schema/shared/src/main/scala/zio/schema/annotation/rejectExtraFields.scala index efb421573..28ecef7b0 100644 --- a/zio-schema/shared/src/main/scala/zio/schema/annotation/rejectExtraFields.scala +++ b/zio-schema/shared/src/main/scala/zio/schema/annotation/rejectExtraFields.scala @@ -1,3 +1,6 @@ package zio.schema.annotation +/** + * Annotation specifying that deserialization should reject payloads that contain more fields than specified. + */ final case class rejectExtraFields() extends scala.annotation.StaticAnnotation diff --git a/zio-schema/shared/src/main/scala/zio/schema/annotation/transientCase.scala b/zio-schema/shared/src/main/scala/zio/schema/annotation/transientCase.scala index c0f126d30..f7458092d 100644 --- a/zio-schema/shared/src/main/scala/zio/schema/annotation/transientCase.scala +++ b/zio-schema/shared/src/main/scala/zio/schema/annotation/transientCase.scala @@ -1,3 +1,7 @@ package zio.schema.annotation +/** + * Annotation specifying that serialization should make no effort to encode + * the case to which the annotation is applied. + */ case class transientCase() extends scala.annotation.StaticAnnotation diff --git a/zio-schema/shared/src/main/scala/zio/schema/annotation/transientField.scala b/zio-schema/shared/src/main/scala/zio/schema/annotation/transientField.scala index 12cf1abe6..4f39da1c2 100644 --- a/zio-schema/shared/src/main/scala/zio/schema/annotation/transientField.scala +++ b/zio-schema/shared/src/main/scala/zio/schema/annotation/transientField.scala @@ -1,3 +1,9 @@ package zio.schema.annotation +/** + * Annotation specifying that serialization should make no effort to encode + * the field to which the annotation is applied. + * + * This is the dual of `@optionalField`. + */ final case class transientField() extends scala.annotation.StaticAnnotation