diff --git a/README.md b/README.md index 3db40e880..4cc96ae0c 100644 --- a/README.md +++ b/README.md @@ -290,29 +290,39 @@ different policy. ### Annotations -| Annotation | Property | Description | -|-----------------------|------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `@XmlSerialName` | | Specify more detailed name information than can be provided by `kotlinx.serialization.SerialName`. In particular, it is not reliably possible to distinguish between `@SerialName` and the type name. We also need to specify namespace and prefix information. | -| | `value: String` | The local part of the name | -| | `namespace: String` | The namespace to use | -| | `val prefix: String` | The prefix to use | -| `@XmlPolyChildren` | | Mostly legacy annotation that allows specifying valid child tags for polymorphic resolution. | -| | `value: Array` | Each string specifies a child according to the following format: `childSerialName[=[prefix:]localName]`. The `childSerialName` is the name value of the descriptor. By default that would be the class name, but `@SerialName` will change that. If the name is prefixed with a `.` the package name of the container will be prefixed. Prefix is the namespace prefix to use (the namespace will be looked up based upon this). Localname allows to specify the local name of the tag. | -| `@XmlChildrenName` | | Used in lists. This causes the children to be serialized as separate tags in an outer tag. The outer tag name is determined regularly. | -| `@XmlKeyName` | | Used to specify the key of map entries. The parameters are the same as `@XmlSerialName` | -| `@XmlElement` | | Force a property to be either serialized as tag or attribute. | -| | `value: Boolean` | `true` to indicate serialization as tag, `false` to indicate serialization as attribute. Note that not all values can be serialized as attribute | -| `@XmlValue` | | Force a property to be element content. Note that only one field can be element content and tags would not be expected. When applied on `CompactFragment` this is treated specially. | -| `@XmlDefault` | | Older versions of the framework do not support default values. This annotation allows a default value to be specified. The default value will not be written out if matched. | -| | `value: String` | The default value used if no value is specified. The value is parsed as if there was textual substitution of this value into the serialized XML. | -| `@XmlBefore` | | Annotation to support serialization order. | -| | `value: Array` | All the children that should be serialized after this one (uses the `@SerialName` value or field name) | -| `@XmlAfter` | | Annotation to support serialization order. | -| | `value: Array` | All the children that should be serialized before this one (uses the `@SerialName` value or field name) | -| `@XmlCData` | | Force serialization as CData. | -| `@XmlMixed` | | When specified on a polymorphic list it will store mixed content (like html) where text is done as Strings. | -| `@XmlOtherAttributes` | | Can be specified on a `Map` to store unsupported attributes. | - +| Annotation | Property | Description | +|-------------------------|------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `@XmlSerialName` | | Specify more detailed name information than can be provided by `kotlinx.serialization.SerialName`. In particular, it is not reliably possible to distinguish between `@SerialName` and the type name. We also need to specify namespace and prefix information. | +| | `value: String` | The local part of the name | +| | `namespace: String` | The namespace to use | +| | `prefix: String` | The prefix to use | +| `@XmlNamespaceDeclSpec` | | Annotation allowing to specify namespaces specifications to be generated upon the element. As multiple annotations are not supported by the plugin this uses a single string. The string separates the namespaces using a semicolon (`;`). Each declaration is of the form (prefix)=(namespace). To specify the default namespace it is valid to omit the equals sign. | +| | `value: String` | The actual specification: `"prefix1=urn:namespace1;defaultNamespace"` | +| `@XmlPolyChildren` | | Mostly legacy annotation that allows specifying valid child tags for polymorphic resolution. | +| | `value: Array` | Each string specifies a child according to the following format: `childSerialName[=[prefix:]localName]`. The `childSerialName` is the name value of the descriptor. By default that would be the class name, but `@SerialName` will change that. If the name is prefixed with a `.` the package name of the container will be prefixed. Prefix is the namespace prefix to use (the namespace will be looked up based upon this). Localname allows to specify the local name of the tag. | +| `@XmlChildrenName` | | Used in lists. This causes the children to be serialized as separate tags in an outer tag. The outer tag name is determined regularly. | +| | `value: String` | The local part of the name | +| | `namespace: String` | The namespace to use | +| | `prefix: String` | The prefix to use | +| `@XmlKeyName` | | Used to specify the key of map entries. | +| | `value: String` | The local part of the name | +| | `namespace: String` | The namespace to use | +| | `prefix: String` | The prefix to use | +| `@XmlElement` | | Force a property to be either serialized as tag or attribute. | +| | `value: Boolean` | `true` to indicate serialization as tag, `false` to indicate serialization as attribute. Note that not all values can be serialized as attribute | +| `@XmlValue` | | Force a property to be content of a tag. This is both for text content, but if the type is a list of tag-like types (`Node`, `Element`, `CompactFragment`) it will also allow mixed content of tags not supported by the base type. | +| | `value: Boolean` | | +| `@XmlId` | | Annotation to mark the value as an ID attribute. This implies that the element is an attribute. | +| `@XmlIgnoreWhitespace` | | Determine whether whitespace should be ignored or preserved for the tag. | +| | `value: Boolean` | `true` if whitespace is to be ignored, `false` if preserved. | +| `@XmlOtherAttributes` | | Can be specified on a `Map` to store unsupported attributes. | +| `@XmlCData` | | Mark the property for serialization as CData, rather than text (where appropriate). It also means that the value is not written as attribute. | +| `@XmlDefault` | | Older versions of the framework do not support default values. This annotation allows a default value to be specified. The default value will not be written out if matched. | +| | `value: String` | The default value used if no value is specified. The value is parsed as if there was textual substitution of this value into the serialized XML. | +| `@XmlBefore` | | Require this property to be serialized before other (sibling) properties. The names are the serialNames of the properties being serialized (not XML names). Together `@XmlBefore` and `@XmlAfter` define a partial order over the properties. | +| | `value: Array` | All the children that should be serialized after this one (uses the `@SerialName` value or field name) | +| `@XmlAfter` | | Require this property to be serialized after other (sibling) properties. The names are the serialNames of the properties being serialized (not XML names). | +| | `value: Array` | All the children that should be serialized before this one (uses the `@SerialName` value or field name) | ### Special types These types have contextual support by default (without needed user intervention), diff --git a/serialization/src/commonMain/kotlin/nl/adaptivity/xmlutil/serialization/annotations.kt b/serialization/src/commonMain/kotlin/nl/adaptivity/xmlutil/serialization/annotations.kt index 0051748a9..140ea6b01 100644 --- a/serialization/src/commonMain/kotlin/nl/adaptivity/xmlutil/serialization/annotations.kt +++ b/serialization/src/commonMain/kotlin/nl/adaptivity/xmlutil/serialization/annotations.kt @@ -29,9 +29,10 @@ import nl.adaptivity.xmlutil.XmlEvent /** * Specify more detailed name information than can be provided by [kotlinx.serialization.SerialName]. - * @property value The local part of the name - * @property namespace The namespace to use - * @property prefix the Prefix to use + * + * @property value The local part of the name. + * @property namespace The namespace to use. + * @property prefix the Prefix to use. */ @SerialInfo @Target(AnnotationTarget.CLASS, AnnotationTarget.PROPERTY) @@ -47,7 +48,7 @@ public annotation class XmlSerialName( * separates the namespaces using a semicolon (`;`). Each declaration is of the form * (prefix)=(namespace). To specify the default namespace it is valid to omit the equals sign. * - * @property value The actual specification: `"prefix1=urn:namespace1;defaultNamespace"` + * @property value The actual specification: `"prefix1=urn:namespace1;defaultNamespace"`. */ @ExperimentalXmlUtilApi @SerialInfo @@ -69,15 +70,19 @@ public val XmlNamespaceDeclSpec.namespaces: List } /** - * Indicate the valid poly children for this element + * Indicate the valid poly children for this element. */ @SerialInfo @Target(AnnotationTarget.PROPERTY) public annotation class XmlPolyChildren(val value: Array) /** - * Specify additional information about child values. This is only used for primitives, not for classes that have their - * own independent name + * Used in lists. This causes the children to be serialized as separate tags in an outer tag. The + * outer tag name is determined regularly. + * + * @property value The local part of the name. + * @property namespace The namespace to use. + * @property prefix the Prefix to use. */ @SerialInfo @Target(AnnotationTarget.CLASS, AnnotationTarget.PROPERTY) @@ -88,8 +93,11 @@ public annotation class XmlChildrenName( ) /** - * Specify additional information about child values. This is only used for primitives, not for classes that have their - * own independent name + * Used to specify the key of map entries. + * + * @property value The local part of the name. + * @property namespace The namespace to use. + * @property prefix the Prefix to use. */ @SerialInfo @Target(AnnotationTarget.PROPERTY) @@ -100,15 +108,18 @@ public annotation class XmlKeyName( ) /** - * Force a property that could be an attribute to be an element + * Force a property that could be an attribute to be an element. + * + * @property value `true` to indicate serialization as tag, `false` to indicate serialization as + * attribute. Note that not all values can be serialized as attribute. */ @SerialInfo @Target(AnnotationTarget.CLASS, AnnotationTarget.PROPERTY) public annotation class XmlElement(val value: Boolean = true) /** - * Force a property to be content of the tag. This is both for text content, but if the type is - * a list of tag-like types (`Node`, `Element`, `CompactFragment` it will also allow mixed content) + * Force a property to be content of a tag. This is both for text content, but if the type is + * a list of tag-like types (`Node`, `Element`, `CompactFragment`) it will also allow mixed content * of tags not supported by the base type. */ @SerialInfo @@ -150,17 +161,23 @@ public annotation class XmlOtherAttributes public annotation class XmlCData(val value: Boolean = true) /** - * Allow a property to be omitted with a default serialized string + * Older versions of the framework do not support default values. This annotation allows a default + * value to be specified. The default value will not be written out if matched. + * + * @property value The default value used if no value is specified. The value is parsed as if there + * was textual substitution of this value into the serialized XML. */ @SerialInfo @Target(AnnotationTarget.PROPERTY) public annotation class XmlDefault(val value: String) /** - * Require this property to be serialized before other (sibling) properties. - * The names are the serialNames of the properties being serialized (not - * XML names). Together [XmlBefore] and [XmlAfter] define a partial order - * over the properties. + * Require this property to be serialized before other (sibling) properties. The names are the + * serialNames of the properties being serialized (not XML names). Together [XmlBefore] and + * [XmlAfter] define a partial order over the properties. + * + * @property value All the children that should be serialized after this one (uses the + * [kotlinx.serialization.SerialName] value or field name). */ @SerialInfo @Retention(AnnotationRetention.BINARY) @@ -168,9 +185,11 @@ public annotation class XmlDefault(val value: String) public annotation class XmlBefore(vararg val value: String) /** - * Require this property to be serialized after other (sibling) properties. - * The names are the serialNames of the properties being serialized (not - * XML names). + * Require this property to be serialized after other (sibling) properties. The names are the + * serialNames of the properties being serialized (not XML names). + * + * @property value All the children that should be serialized before this one (uses the + * [kotlinx.serialization.SerialName] value or field name). */ @SerialInfo @Retention(AnnotationRetention.BINARY)