HSEARCH-3372 Complete the javadoc of the POJO mapper APIs

mapper/pojo/src/main/java/org/hibernate/search/mapper/pojo/extractor/ContainerExtractor.java

@@ -8,10 +8,36 @@
 
 import java.util.stream.Stream;
 
+import org.hibernate.search.mapper.pojo.extractor.builtin.BuiltinContainerExtractors;
+
+/**
+ * An extractor of values from a container.
+ * <p>
+ * Container extractors tell Hibernate Search how to extract values from object properties:
+ * no extractor would mean using the property value directly,
+ * a {@link BuiltinContainerExtractors#COLLECTION collection element extractor}
+ * would extract each element of a collection,
+ * a {@link BuiltinContainerExtractors#MAP_KEY map keys extractor}
+ * would extract each key of a map,
+ * etc.
+ * @param <C> The type of containers this extractor can extract values from.
+ * @param <V> The type of values extracted by this extractor.
+ * @see ContainerExtractorPath
+ * @see BuiltinContainerExtractors
+ */
 public interface ContainerExtractor<C, V> {
 
+	/**
+	 * @param container A container to extract values from.
+	 * @return A stream of values extracted from the given container.
+	 * The stream will be {@link Stream#close()} by the caller.
+	 */
 	Stream<V> extract(C container);
 
+	/**
+	 * @return {@code true} if this extractor's {@link #extract(Object)} method may return streams with more than one value.
+	 * {@code false} if it will never return streams with more than one value.
+	 */
 	default boolean isMultiValued() {
 		return true;
 	}

mapper/pojo/src/main/java/org/hibernate/search/mapper/pojo/extractor/ContainerExtractorDefinitionContext.java

@@ -6,6 +6,15 @@
  */
 package org.hibernate.search.mapper.pojo.extractor;
 
+import java.util.List;
+
+/**
+ * A context to assign names to container extractor implementations.
+ *
+ * @see ContainerExtractor
+ * @see ContainerExtractorPath#explicitExtractor(String)
+ * @see ContainerExtractorPath#explicitExtractors(List)
+ */
 @SuppressWarnings("rawtypes") // We need to allow raw container types, e.g. MapValueExtractor.class
 public interface ContainerExtractorDefinitionContext {
 

mapper/pojo/src/main/java/org/hibernate/search/mapper/pojo/extractor/ContainerExtractorPath.java

@@ -12,26 +12,25 @@
 import java.util.Objects;
 import java.util.StringJoiner;
 
+import org.hibernate.search.mapper.pojo.extractor.builtin.BuiltinContainerExtractors;
+
 /**
- * ContainerExtractorPath represents a list of container extractors to be applied to a property.
- * <p>
- * Container extractors tell Hibernate Search how to extract values:
- * an empty container extractor path means the property value should be taken as is,
- * a collection element extractor would extract each element of a collection,
- * a map keys extractor would extract each key of a map, etc.
- * <p>
- * Container extractor paths can chain multiple extractors,
- * so that for example the extraction of values from a {@code List<List<String>>} can be represented.
+ * A chain of {@link ContainerExtractor container extractors} to be applied one after the other to a property value,
+ * in order to extract other values.
  * <p>
  * The extractors are either represented:
  * <ul>
- * <li>explicitly by their classes, e.g. {@code [MapValuesExtractor.class, CollectionElementExtractor.class]},
- * meaning "apply an instance of MapValuesExtractor on the property value, then apply an instance of
- * CollectionElementExtractor on the map values".
+ * <li>explicitly by their name, e.g. {@code ["map-values", "collection"]},
+ * meaning "apply the 'map-values' extractor to the property value, then apply the 'collection' extractor to the map values".
+ * Names are either {@link BuiltinContainerExtractors built-in}
+ * or {@link ContainerExtractorDefinitionContext registered at bootstrap}.
  * <li>or simply by the "default" path ({@link #defaultExtractors()}),
  * which means "whatever default Hibernate Search manages to apply using its internal extractor resolution algorithm".
  * This second form may result in different "resolved" paths depending on the type of the property it is applied to.
  * </ul>
+ *
+ * @see ContainerExtractor
+ * @see BuiltinContainerExtractors
  */
 public class ContainerExtractorPath {
 
@@ -59,7 +58,7 @@ public static ContainerExtractorPath noExtractors() {
 	/**
 	 * @param extractorName A container extractor referenced by its name.
 	 * @return A path that will apply the referenced container extractor.
-	 * @see org.hibernate.search.mapper.pojo.extractor.builtin.BuiltinContainerExtractors
+	 * @see BuiltinContainerExtractors
 	 */
 	public static ContainerExtractorPath explicitExtractor(String extractorName) {
 		return new ContainerExtractorPath(
@@ -124,14 +123,28 @@ else if ( explicitExtractorNames.isEmpty() ) {
 		}
 	}
 
+	/**
+	 * @return {@code true} if this path represents the default extractor(s),
+	 * which will be determined automatically based on the property type.
+	 * {@code false} otherwise.
+	 */
 	public boolean isDefault() {
 		return applyDefaultExtractors;
 	}
 
+	/**
+	 * @return {@code true} if this path is empty,
+	 * i.e. it represents direct access to the property value.
+	 * {@code false} otherwise.
+	 */
 	public boolean isEmpty() {
 		return !isDefault() && explicitExtractorNames.isEmpty();
 	}
 
+	/**
+	 * @return The list of extractor names explicitly referenced by this path.
+	 * Empty if this path represents the default extractor(s).
+	 */
 	public List<String> getExplicitExtractorNames() {
 		return explicitExtractorNames;
 	}

mapper/pojo/src/main/java/org/hibernate/search/mapper/pojo/extractor/builtin/BuiltinContainerExtractors.java

@@ -6,19 +6,51 @@
  */
 package org.hibernate.search.mapper.pojo.extractor.builtin;
 
+import org.hibernate.search.mapper.pojo.extractor.ContainerExtractor;
+
+/**
+ * The names of {@link ContainerExtractor container extractors} available in Hibernate Search out of the box.
+ */
 public class BuiltinContainerExtractors {
 
 	private BuiltinContainerExtractors() {
 	}
 
+	/**
+	 * The name of an extractor that extracts elements from an object array.
+	 */
 	public static final String ARRAY = "array";
+	/**
+	 * The name of an extractor that extracts elements from a {@link java.util.Collection}.
+	 */
 	public static final String COLLECTION = "collection";
+	/**
+	 * The name of an extractor that extracts elements from an {@link Iterable}.
+	 */
 	public static final String ITERABLE = "iterable";
+	/**
+	 * The name of an extractor that extracts keys from a {@link java.util.Map}.
+	 */
 	public static final String MAP_KEY = "map-key";
+	/**
+	 * The name of an extractor that extracts values from a {@link java.util.Map}.
+	 */
 	public static final String MAP_VALUE = "map-value";
+	/**
+	 * The name of an extractor that extracts the value from an {@link java.util.OptionalDouble}.
+	 */
 	public static final String OPTIONAL_DOUBLE = "optional-double";
+	/**
+	 * The name of an extractor that extracts the value from an {@link java.util.OptionalInt}.
+	 */
 	public static final String OPTIONAL_INT = "optional-int";
+	/**
+	 * The name of an extractor that extracts the value from an {@link java.util.OptionalLong}.
+	 */
 	public static final String OPTIONAL_LONG = "optional-long";
+	/**
+	 * The name of an extractor that extracts the value from an {@link java.util.Optional}.
+	 */
 	public static final String OPTIONAL = "optional";
 
 }

mapper/pojo/src/main/java/org/hibernate/search/mapper/pojo/mapping/definition/annotation/AnnotationMappingDefinitionContext.java

@@ -8,10 +8,21 @@
 
 import java.util.Set;
 
+/**
+ * A context to define annotation mapping.
+ */
 public interface AnnotationMappingDefinitionContext {
 
+	/**
+	 * @param annotatedType A type to scan for annotations.
+	 * @return {@code this}, for method chaining.
+	 */
 	AnnotationMappingDefinitionContext add(Class<?> annotatedType);
 
+	/**
+	 * @param annotatedTypes A set of types to scan for annotations.
+	 * @return {@code this}, for method chaining.
+	 */
 	AnnotationMappingDefinitionContext add(Set<Class<?>> annotatedTypes);
 
 }

mapper/pojo/src/main/java/org/hibernate/search/mapper/pojo/mapping/definition/annotation/DocumentId.java

@@ -13,7 +13,9 @@
 import java.lang.annotation.Target;
 
 /**
- * @author Yoann Rodiere
+ * Maps a property to the identifier of documents in the index.
+ * <p>
+ * This annotation is only taken into account on {@link Indexed} types.
  */
 @Documented
 @Target({ ElementType.METHOD, ElementType.FIELD })

mapper/pojo/src/main/java/org/hibernate/search/mapper/pojo/mapping/definition/annotation/FullTextField.java

@@ -19,7 +19,7 @@
 import org.hibernate.search.engine.backend.types.TermVector;
 
 /**
- * A full-text field in the full text index, potentially holding multiple tokens (words) of text.
+ * Maps a property to a full-text field in the index, potentially holding multiple tokens (words) of text.
  * <p>
  * Note that this annotation only creates tokenized (multi-word) text fields.
  * As a result:
@@ -51,32 +51,35 @@
 	 */
 	String analyzer();
 
-	/**
-	 * @return Whether projections are enabled for this field.
-	 * @see GenericField#projectable()
-	 */
-	Projectable projectable() default Projectable.DEFAULT;
-
 	/**
 	 * @return Whether index-time scoring information should be stored or not.
 	 * @see Norms
 	 */
 	Norms norms() default Norms.DEFAULT;
 
 	/**
-	 * @return Whether this field should be searchable.
-	 * @see Searchable
+	 * @return The term vector storing strategy.
+	 * @see TermVector
 	 */
-	Searchable searchable() default Searchable.DEFAULT;
+	TermVector termVector() default TermVector.DEFAULT;
 
 	/**
-	 * @return The term vector storing strategy
-	 * @see TermVector
+	 * @return Whether projections are enabled for this field.
+	 * @see GenericField#projectable()
+	 * @see Projectable
 	 */
-	TermVector termVector() default TermVector.DEFAULT;
+	Projectable projectable() default Projectable.DEFAULT;
+
+	/**
+	 * @return Whether this field should be searchable.
+	 * @see GenericField#sortable()
+	 * @see Searchable
+	 */
+	Searchable searchable() default Searchable.DEFAULT;
 
 	/**
 	 * @return A reference to the value bridge to use for this field.
+	 * @see GenericField#valueBridge()
 	 * @see ValueBridgeRef
 	 */
 	ValueBridgeRef valueBridge() default @ValueBridgeRef;

mapper/pojo/src/main/java/org/hibernate/search/mapper/pojo/mapping/definition/annotation/GenericField.java

@@ -18,14 +18,16 @@
 import org.hibernate.search.engine.backend.types.Projectable;
 
 /**
- * A generic annotation that will work for any supported type of field in the full text index:
- * full-text, keyword (non-analyzed) text, integer, date, ...
+ * Maps an entity property to a field in the index.
+ * <p>
+ * This is a generic annotation that will work for any type of field supported by the backend:
+ * {@link String}, {@link Integer}, {@link java.time.LocalDate}, ...
  * <p>
  * Note that this annotation, being generic, does not offer configuration options
  * that are specific to only some types of fields.
  * Use more specific annotations if you want that kind of configuration.
  * For example, to define a tokenized (multi-word) text field, use {@link FullTextField}.
- * To define a non-tokenized (single-word) text field, use {@link KeywordField}.
+ * To define a non-tokenized (single-word), but normalized (lowercased, ...) text field, use {@link KeywordField}.
  */
 @Documented
 @Target({ ElementType.METHOD, ElementType.FIELD })
@@ -55,7 +57,7 @@
 	Searchable searchable() default Searchable.DEFAULT;
 
 	/**
-	 * @return An optional value to replace any null value.
+	 * @return A value used instead of null values when indexing.
 	 */
 	String indexNullAs() default AnnotationDefaultValues.DO_NOT_INDEX_NULL;
 

mapper/pojo/src/main/java/org/hibernate/search/mapper/pojo/mapping/definition/annotation/IdentifierBridgeRef.java

@@ -15,43 +15,37 @@
 import org.hibernate.search.mapper.pojo.bridge.mapping.BridgeBuilder;
 
 /**
- * Reference to the identifier bridge to use for a {@link DocumentId}.
+ * A reference to the identifier bridge to use for a {@link DocumentId}.
  * <p>
  * Either a bridge or a bridge builder can be provided, but never both.
  * Reference can be obtained using either a name or a type.
- *
- * @author Yoann Rodiere
  */
 @Documented
 @Target({}) // Only used as a component in other annotations
 @Retention(RetentionPolicy.RUNTIME)
 public @interface IdentifierBridgeRef {
 
 	/**
-	 * Provide the bridge name to get the bridge reference.
-	 *
-	 * @return the bridge name
+	 * Reference an identifier bridge by its bean name.
+	 * @return The bean name of the  identifier bridge.
 	 */
 	String name() default "";
 
 	/**
-	 * Provide the bridge type to get the bridge reference.
-	 *
-	 * @return the bridge type
+	 * Reference an identifier bridge by its type.
+	 * @return The type of the  identifier bridge.
 	 */
-	Class<? extends IdentifierBridge<?>> type() default UndefinedBridgeImplementationType.class;
+	Class<? extends IdentifierBridge> type() default UndefinedBridgeImplementationType.class;
 
 	/**
-	 * Provide the builder bridge name to get the bridge reference.
-	 *
-	 * @return the bridge builder name
+	 * Reference an identifier bridge by the bean name of its builder.
+	 * @return The bean name of the  identifier bridge builder.
 	 */
 	String builderName() default "";
 
 	/**
-	 * Provide the builder bridge type to get the bridge reference.
-	 *
-	 * @return the bridge builder type
+	 * Reference an identifier bridge by the type of its builder.
+	 * @return The type of the  identifier bridge builder.
 	 */
 	Class<? extends BridgeBuilder<? extends IdentifierBridge<?>>> builderType() default UndefinedBuilderImplementationType.class;
 

mapper/pojo/src/main/java/org/hibernate/search/mapper/pojo/mapping/definition/annotation/Indexed.java

@@ -13,7 +13,7 @@
 import java.lang.annotation.Target;
 
 /**
- * @author Yoann Rodiere
+ * Maps an entity type to an index.
  */
 @Documented
 @Target({ ElementType.TYPE })