Add scaladoc to annotations (#550)

Co-authored-by: Daniel Vigovszky <daniel.vigovszky@gmail.com>

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

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

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

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

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

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

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

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

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

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

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