Style and Javadoc improvements

Author: Sanne

engine/src/main/java/org/hibernate/search/backend/impl/StreamingOperationSelectionDelegate.java

@@ -29,7 +29,7 @@
 
 /**
  * Sends a single operation to the related backends, considering the sharding strategy.
- * This delegates to {@link org.hibernate.search.indexes.spi.IndexManager#performStreamOperation(LuceneWork, boolean)}
+ * This delegates to {@link org.hibernate.search.indexes.spi.IndexManager#performStreamOperation(LuceneWork, IndexingMonitor, boolean)}
  * so it's suited for streams of many LuceneWork operations which don't need strict ordering.
  *
  * @author Sanne Grinovero

engine/src/main/java/org/hibernate/search/cfg/EntityMapping.java

@@ -105,7 +105,7 @@ public ClassBridgeMapping classBridge(Class<?> impl) {
 	 * Registers the given class bridge for the currently configured entity type. Any subsequent analyzer, parameter
 	 * etc. configurations apply to this class bridge.
 	 *
-	 * @param instance a class bridge instance
+	 * @param classBridge a class bridge instance
 	 * @return a new {@link ClassBridgeMapping} following the method chaining pattern
 	 * @experimental This method is considered experimental and it may be altered or removed in future releases
 	 * @throws org.hibernate.search.SearchException in case the same bridge instance is passed more than once for the

engine/src/main/java/org/hibernate/search/engine/spi/SearchFactoryImplementor.java

@@ -78,9 +78,8 @@ public interface SearchFactoryImplementor extends SearchFactoryIntegrator {
 	StatisticsImplementor getStatisticsImplementor();
 
 	/**
-	 * @return true if we are allowed to inspect entity state to
-	 *         potentially skip some indexing operations.
-	 *         Can be disabled to get pre-3.4 behavior (always rebuild document)
+	 * @return {@code true} if we are allowed to inspect entity state to skip some indexing operations.
+	 *         Can be disabled to get pre-3.4 behavior which always rebuilds the document.
 	 */
 	boolean isDirtyChecksEnabled();
 

engine/src/main/java/org/hibernate/search/impl/ReflectionReplacingSearchConfiguration.java

@@ -50,8 +50,8 @@ public final class ReflectionReplacingSearchConfiguration implements SearchConfi
 	 * instance, with the exception of {@link #getReflectionManager()} which will return the constructor
 	 * defined ReflectionManager.
 	 *
-	 * @param reflectionManager
-	 * @param cfg
+	 * @param reflectionManager the current reflection manager
+	 * @param cfg the search configuration
 	 */
 	public ReflectionReplacingSearchConfiguration(ReflectionManager reflectionManager, SearchConfiguration cfg) {
 		this.reflectionManager = reflectionManager;

engine/src/main/java/org/hibernate/search/indexes/impl/DirectoryBasedIndexManager.java

@@ -51,8 +51,8 @@
 import org.hibernate.search.util.logging.impl.LoggerFactory;
 
 /**
- * This implementation of IndexManager is coupled to a
- * DirectoryProvider and a DirectoryBasedReaderProvider
+ * This implementation of {@code IndexManager} is coupled to a
+ * {@code DirectoryProvider} and a {@code DirectoryBasedReaderProvider}.
  *
  * @author Sanne Grinovero <sanne@hibernate.org> (C) 2011 Red Hat Inc.
  */

engine/src/main/java/org/hibernate/search/indexes/interceptor/EntityIndexingInterceptor.java

@@ -30,7 +30,7 @@
  * the explicit indexing control API such <code>org.hibernate.search.FullTextSession.index(T)</code>
  * or <code>purge</code>, <purgeAll>.
  *
- * @experimental: {@link IndexingOverride} might be updated
+ * @experimental {@link IndexingOverride} might be updated
  *
  * @author Emmanuel Bernard <emmanuel@hibernate.org>
  */
@@ -70,11 +70,11 @@ public interface EntityIndexingInterceptor<T> {
 
 	/**
 	 * A CollectionUpdate event is fired on collections included in an indexed entity, for example when using
-	 * {@link IndexedEmbedded} This event is triggered on each indexed domain instance T contained in such a collection;
+	 * {@link org.hibernate.search.annotations.IndexedEmbedded} This event is triggered on each indexed domain instance T contained in such a collection;
 	 * this is generally similar to a {@link #onUpdate(Object)} event.
 	 *
-	 * @param entity
-	 *            The entity instance
+	 * @param entity The entity instance
+	 *
 	 * @return Return {@link IndexingOverride#APPLY_DEFAULT} to have the instance removed and re-added to the index as
 	 *         normal; return a different value to override the behaviour.
 	 */

engine/src/main/java/org/hibernate/search/indexes/serialization/impl/PluggableSerializationLuceneWorkSerializer.java

@@ -59,7 +59,7 @@
 public class PluggableSerializationLuceneWorkSerializer implements LuceneWorkSerializer {
 	private static Log log = LoggerFactory.make();
 
-	private SearchFactoryImplementor searchFactory;
+	private final SearchFactoryImplementor searchFactory;
 	private SerializationProvider provider;
 
 	public PluggableSerializationLuceneWorkSerializer(SerializationProvider provider, SearchFactoryImplementor searchFactory) {
@@ -212,7 +212,7 @@ else if ( safeField.tokenStreamValue() != null ) {
 					throw log.unknownFieldType( safeField.getClass() );
 				}
 			}
-			else if (fieldable instanceof Serializable) { //Today Fieldable is Serializable but for how long?
+			else if ( fieldable != null ) { //Today Fieldable is Serializable but for how long?
 				serializer.addFieldWithSerializableFieldable( toByteArray( fieldable ) );
 			}
 			else {

engine/src/main/java/org/hibernate/search/indexes/serialization/spi/LuceneWorkSerializer.java

@@ -25,7 +25,7 @@
 import org.hibernate.search.backend.LuceneWork;
 
 /**
- * For clustering we need some way to serialize the LuceneWork(s)
+ * For clustering we need some way to serialize the {@code LuceneWork} instances.
  * to the other nodes.
  *
  * @author Sanne Grinovero <sanne@hibernate.org> (C) 2011 Red Hat Inc.

engine/src/main/java/org/hibernate/search/metadata/PropertyDescriptor.java

@@ -39,7 +39,7 @@ public interface PropertyDescriptor extends FieldContributor {
 	 *
 	 * @return {@code true} if the property is the document id, {@code false} otherwise
 	 *
-	 * @see {@link org.hibernate.search.annotations.DocumentId}
+	 * @see org.hibernate.search.annotations.DocumentId
 	 */
 	boolean isId();
 }

engine/src/main/java/org/hibernate/search/query/dsl/QueryBuilder.java

@@ -25,7 +25,7 @@
 package org.hibernate.search.query.dsl;
 
 /**
- * Builds up Lucene queries for a given entity type following the fluent API pattern. The resulting {@link Query} can
+ * Builds up Lucene queries for a given entity type following the fluent API pattern. The resulting {@link org.apache.lucene.search.Query} can
  * be obtained from the final {@link Termination} object of the invocation chain.
  * </p>
  * If required, the resulting {@code Query} instance can be modified or combined with other queries, be them created