GH-2431 - Improve converter documentation and polish related code.

Fixes #2431.

Author: michael-simons

src/main/asciidoc/appendix/conversions.adoc

@@ -208,11 +208,13 @@ If you need multiple converters in your application, you can add as many as you
 === For specific attributes only
 
 If you need conversions only for some specific attributes, we provide `@ConvertWith`.
-This is an annotation that can be put on attributes carrying a `Neo4jPersistentPropertyConverter` on its `converter` attribute
+This is an annotation that can be put on attributes of both entities (`@Node`) and relationship properties (`@RelationshipProperties`)
+It defines a `Neo4jPersistentPropertyConverter` via the `converter` attribute
 and an optional `Neo4jPersistentPropertyConverterFactory` to construct the former.
 With an implementation of `Neo4jPersistentPropertyConverter` all specific conversions for a given type can be addressed.
 
 We provide `@DateLong` and `@DateString` as meta-annotated annotations for backward compatibility with Neo4j-OGM schemes not using native types.
+Those are meta annotated annotations building on the concept above.
 
 [[custom.conversions.composite-properties]]
 ==== Composite properties

src/main/java/org/springframework/data/neo4j/core/convert/ConvertWith.java

@@ -48,8 +48,14 @@
 @API(status = API.Status.STABLE, since = "6.0")
 public @interface ConvertWith {
 
+	/**
+	 * @return The converter to instantiated for converting attributes to properties and vice versa.
+	 */
 	Class<? extends Neo4jPersistentPropertyConverter<?>> converter() default UnsetConverter.class;
 
+	/**
+	 * @return An alternative to {@link #converter()}, for all the scenarios in which constructing a converter is more effort than a constructor call.
+	 */
 	Class<? extends Neo4jPersistentPropertyConverterFactory> converterFactory() default DefaultNeo4jPersistentPropertyConverterFactory.class;
 
 	/**

src/main/java/org/springframework/data/neo4j/core/schema/CompositeProperty.java

@@ -35,6 +35,7 @@
 import org.neo4j.driver.Values;
 import org.springframework.beans.BeanUtils;
 import org.springframework.core.GenericTypeResolver;
+import org.springframework.core.annotation.AliasFor;
 import org.springframework.data.neo4j.core.convert.ConvertWith;
 import org.springframework.data.neo4j.core.convert.Neo4jConversionService;
 import org.springframework.data.neo4j.core.convert.Neo4jPersistentPropertyConverter;
@@ -66,12 +67,11 @@
 @API(status = API.Status.STABLE, since = "6.0")
 public @interface CompositeProperty {
 
-	String UNSET = new String("");
-
 	/**
 	 * @return A converter that allows to store arbitrary objects as decomposed maps on nodes and relationships. The
 	 * default converter allows only maps as composite properties.
 	 */
+	@AliasFor(annotation = ConvertWith.class, value = "converter")
 	Class<? extends Neo4jPersistentPropertyToMapConverter> converter() default CompositeProperty.DefaultToMapConverter.class;
 
 	/**

src/test/java/org/springframework/data/neo4j/integration/shared/conversion/ListPropertyConversionIT.java

@@ -171,7 +171,7 @@ static class DomainObjectWithListOfConvertables {
 		@CompositeProperty(converter = ListDecomposingConverter.class, delimiter = "", prefix = "someprefix")
 		private List<SomeConvertableClass> collectedData;
 
-		@ConvertWith(converter = F.class)
+		@ConvertWith(converter = SomeconvertableClassConverter.class)
 		private List<SomeConvertableClass> anotherSet;
 
 	}
@@ -253,7 +253,7 @@ public List<SomeConvertableClass> compose(Map<String, Value> source,
 		}
 	}
 
-	static class F implements Neo4jPersistentPropertyConverter<List<SomeConvertableClass>> {
+	static class SomeconvertableClassConverter implements Neo4jPersistentPropertyConverter<List<SomeConvertableClass>> {
 
 		@Override public Value write(List<SomeConvertableClass> source) {