CORDA-553 - Review Comments

core/src/main/kotlin/net/corda/core/serialization/CordaSerializationTransformEnumDefault.kt

@@ -1,14 +1,89 @@
 package net.corda.core.serialization
 
 /**
+ * This annotation is used to mark an enumerated type as having had multiple members added, It acts
+ * as a container annotation for instances of [CordaSerializationTransformEnumDefault], each of which
+ * details individual additions.
  *
+ * @property value an array of [CordaSerializationTransformEnumDefault].
+ *
+ * NOTE: Order is important, new values should always be added before any others
+ *
+ * ```
+ *  // initial implementation
+ *  enum class ExampleEnum {
+ *    A, B, C
+ *  }
+ *
+ *  // First alteration
+ *  @CordaSerializationTransformEnumDefaults(
+ *      CordaSerializationTransformEnumDefault("D", "C"))
+ *  enum class ExampleEnum {
+ *    A, B, C, D
+ *  }
+ *
+ *  // Second alteration, new transform is placed at the head of the list
+ *  @CordaSerializationTransformEnumDefaults(
+ *      CordaSerializationTransformEnumDefault("E", "C"),
+ *      CordaSerializationTransformEnumDefault("D", "C"))
+ *  enum class ExampleEnum {
+ *    A, B, C, D, E
+ *  }
+ * ```
+ *
+ * IMPORTANT - Once added (and in production) do NOT remove old annotations. See documentation for
+ * more discussion on this point!.
  */
 @Target(AnnotationTarget.CLASS)
 @Retention(AnnotationRetention.RUNTIME)
 annotation class CordaSerializationTransformEnumDefaults(vararg val value: CordaSerializationTransformEnumDefault)
 
 /**
+ * This annotation is used to mark an enumerated type as having had a new constant appended to it. For
+ * each additional constant added a new annotation should be appended to the class. If more than one
+ * is required the wrapper annotation [CordaSerializationTransformEnumDefaults] should be used to
+ * encapsulate them
  *
+ * @property new [String] equivalent of the value of the new constant
+ * @property old [String] equivalent of the value of the existing constant that deserialisers should
+ * favour when de-serialising a value they have no corresponding value for
+ *
+ * For Example
+ *
+ * Enum before modification:
+ * ```
+ *  enum class ExampleEnum {
+ *    A, B, C
+ *  }
+ * ```
+ *
+ * Assuming at some point a new constant is added it is required we have some mechanism by which to tell
+ * nodes with an older version of the class on their Class Path what to do if they attempt to deserialize
+ * an example of the class with that new value
+ *
+ * ```
+ *  @CordaSerializationTransformEnumDefault("D", "C")
+ *  enum class ExampleEnum {
+ *    A, B, C, D
+ *  }
+ * ```
+ *
+ * So, on deserialisation treat any instance of the enum that is encoded as D as C
+ *
+ * Adding a second new constant requires the wrapper annotation [CordaSerializationTransformEnumDefaults]
+ *
+ * ```
+ *  @CordaSerializationTransformEnumDefaults(
+ *      CordaSerializationTransformEnumDefault("E", "D"),
+ *      CordaSerializationTransformEnumDefault("D", "C"))
+ *  enum class ExampleEnum {
+ *    A, B, C, D, E
+ *  }
+ * ```
+ *
+ * It's fine to assign the second new value a default that may not be present in all versions as in this
+ * case it will work down the transform hierarchy until it finds a value it can apply, in this case it would
+ * try E -> D -> C (when E -> D fails)
  */
 @Target(AnnotationTarget.CLASS)
 @Retention(AnnotationRetention.RUNTIME)

core/src/main/kotlin/net/corda/core/serialization/CordaSerializationTransformRename.kt

@@ -1,13 +1,31 @@
 package net.corda.core.serialization
 
 /**
+ * This annotation is used to mark a class as having had multiple elements renamed as a container annotation for
+ * instances of [CordaSerializationTransformRename], each of which details an individual rename.
  *
+ * @property value an array of [CordaSerializationTransformRename]
+ *
+ * NOTE: Order is important, new values should always be added before existing
+ *
+ * IMPORTANT - Once added (and in production) do NOT remove old annotations. See documentation for
+ * more discussion on this point!.
  */
 @Target(AnnotationTarget.CLASS)
 @Retention(AnnotationRetention.RUNTIME)
 annotation class CordaSerializationTransformRenames(vararg val value: CordaSerializationTransformRename)
 
+// TODO When we have class renaming update the docs
 /**
+ * This annotation is used to mark a class has having had a property element. It is used by the
+ * AMQP deserialiser to allow instances with different versions of the class on their Class Path
+ * to successfully deserialize the object
+ *
+ * NOTE: Renaming of the class itself is not be done with this annotation. For class renaming
+ * see ???
+ *
+ * @property to [String] representation of the properties new name
+ * @property from [String] representation of the properties old new
  *
  */
 @Target(AnnotationTarget.CLASS)