HSEARCH-436 Javadoc fixes and clarifications

engine/src/main/java/org/hibernate/search/SearchFactory.java

@@ -44,7 +44,7 @@ public interface SearchFactory {
 	void optimize();
 
 	/**
-	 * Optimize the index holding <code>entityType</code>
+	 * Optimize the index holding {@code entityType}
 	 *
 	 * @param entityType the entity type (index) to optimize
 	 */
@@ -64,7 +64,7 @@ public interface SearchFactory {
 	 *
 	 * @param clazz The class for which to retrieve the analyzer.
 	 * @return The scoped analyzer for the specified class.
-	 * @throws java.lang.IllegalArgumentException in case <code>clazz == null</code> or the specified
+	 * @throws java.lang.IllegalArgumentException in case {@code clazz == null} or the specified
 	 *                                  class is not an indexed entity.
 	 */
 	Analyzer getAnalyzer(Class<?> clazz);
@@ -87,5 +87,4 @@ public interface SearchFactory {
 	 * @return the IndexReaderAccessor for this SearchFactory
 	 */
 	IndexReaderAccessor getIndexReaderAccessor();
-
 }

engine/src/main/java/org/hibernate/search/annotations/AnalyzerDiscriminator.java

@@ -23,24 +23,22 @@
  */
 package org.hibernate.search.annotations;
 
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
-import java.lang.annotation.ElementType;
-import java.lang.annotation.Documented;
 
 import org.hibernate.search.analyzer.Discriminator;
 
 /**
- * Allows to dynamically select a named analyzer through a <code>Discriminator</code> implementation.
+ * Allows to dynamically select a named analyzer through a {@code Discriminator} implementation.
  *
  * @author Hardy Ferentschik
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ ElementType.TYPE, ElementType.FIELD, ElementType.METHOD })
 @Documented
 public @interface AnalyzerDiscriminator {
-
 	Class<? extends Discriminator> impl();
-
 }

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

@@ -30,8 +30,8 @@
 import org.hibernate.search.util.logging.impl.LoggerFactory;
 
 /**
- * Lazily loaded Services might need a BuilContext to retrieve additional services;
- * in such a case we can wrap a reference to a {@link ServiceManager} and a
+ * Lazily loaded services might need a {@code BuildContext} to retrieve additional services.
+ * In such a case we can wrap a reference to a {@link ServiceManager} and a
  * {@link SearchFactoryImplementor} to create a limited BuildContext:
  * we're out of the boot phase at this point so not all operations are legal.
  *

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

@@ -106,7 +106,7 @@ public void clear() {
 	 * This is meant for resource control for auto flushing of large pending batches.
 	 *
 	 * @return the approximation
-	 * @see Environment#QUEUEINGPROCESSOR_BATCHSIZE
+	 * @see org.hibernate.search.Environment#QUEUEINGPROCESSOR_BATCHSIZE
 	 */
 	public int size() {
 		return approximateWorkQueueSize;

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

@@ -65,7 +65,7 @@
 public class MutableSearchFactory implements SearchFactoryImplementorWithShareableState, SearchFactoryIntegrator {
 	//a reference to the same instance of this class is help by clients and various HSearch services
 	//when changing the SearchFactory internals, only the underlying delegate should be changed.
-	//the volatile ensure that the state is replicated upong underlying factory switch.
+	//the volatile ensure that the state is replicated upon underlying factory switch.
 	private volatile SearchFactoryImplementorWithShareableState delegate;
 
 	//lock to be acquired every time the underlying searchFactory is rebuilt

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

@@ -52,7 +52,7 @@ public SimpleIndexingProgressMonitor() {
 	}
 
 	/**
-	 * Logs progress of indexing job every <code>logAfterNumberOfDocuments</code>
+	 * Logs progress of indexing job every {@code logAfterNumberOfDocuments}
 	 * documents written.
 	 *
 	 * @param logAfterNumberOfDocuments log each time the specified number of documents has been added

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

@@ -51,12 +51,12 @@
 import org.hibernate.search.util.logging.impl.LoggerFactory;
 
 /**
- * Stores references to IndexManager instances, and starts/stops them.
- * Starting IndexManagers happens by creating new EntityIndexBinder instances, while creating the binders
- * if we hit the need for a new IndexManager, or several according to a sharding strategy, the new
- * IndexManagers are started incrementally.
- * Stopping IndexManager can not currently happen decrementally: to stop the IndexManagers all of them
- * are stopped.
+ * Stores references to {@code IndexManager} instances, and starts or stops them.
+ *
+ * Starting {@code IndexManager}s happens by creating new {@code EntityIndexBinder} instances. {@code IndexManager}s are
+ * started successively as they are needed (for example based on the sharding strategy).
+ *
+ * Stopping {@code IndexManager}s can currently only happen all at once.
  *
  * @author Emmanuel Bernard
  * @author Sylvain Vieujot

engine/src/main/java/org/hibernate/search/query/collector/impl/MapFieldCacheCollectorImpl.java

@@ -35,7 +35,7 @@
  * so for large resultsets you should use BigArrayFieldCacheCollectorImpl instead.
  *
  * @author Sanne Grinovero <sanne@hibernate.org> (C) 2011 Red Hat Inc.
- * @see org.hibernate.search.query.collector.BigArrayFieldCacheCollectorImpl
+ * @see org.hibernate.search.query.collector.impl.BigArrayFieldCacheCollectorImpl
  */
 final class MapFieldCacheCollectorImpl extends FieldCacheCollector {
 

engine/src/main/java/org/hibernate/search/query/fieldcache/impl/FieldLoadingStrategy.java

@@ -24,13 +24,13 @@
 import org.apache.lucene.index.IndexReader;
 
 /**
- * Using as composition in implementations of {@link org.hibernate.search.query.collector.FieldCacheCollector},
+ * Using as composition in implementations of {@link org.hibernate.search.query.collector.impl.FieldCacheCollector},
  * so that we can reuse different loading strategies in different kinds
  * of Collectors.
  *
  * @author Sanne Grinovero <sanne@hibernate.org> (C) 2011 Red Hat Inc.
- * @see org.hibernate.search.query.collector.BigArrayFieldCacheCollectorImpl
- * @see org.hibernate.search.query.collector.MapFieldCacheCollectorImpl
+ * @see org.hibernate.search.query.collector.impl.BigArrayFieldCacheCollectorImpl
+ * @see org.hibernate.search.query.collector.impl.MapFieldCacheCollectorImpl
  */
 public interface FieldLoadingStrategy {
 	/**

engine/src/main/java/org/hibernate/search/store/optimization/OptimizerStrategy.java

@@ -32,7 +32,8 @@
 
 /**
  * Controls how and when the indexes are optimized.
- * Implementations need to be threadsafe.
+ *
+ * Note: Implementations need to be threadsafe.
  *
  * @author Emmanuel Bernard
  * @author Sanne Grinovero
@@ -42,12 +43,12 @@ public interface OptimizerStrategy {
 	/**
 	 * Invokes optimize on the IndexWriter; This is invoked when
 	 * an optimization has been explicitly requested by the user API
-	 * using {@link SearchFactory#optimize()} or {@link SearchFactory#optimize(Class)},
+	 * using {@link org.hibernate.search.SearchFactory#optimize()} or {@link org.hibernate.search.SearchFactory#optimize(Class)},
 	 * or at the start or end of a MassIndexer's work.
 	 *
 	 * @param writer the index writer
 	 * @return {@code true} if optimisation occurred, {@code false} otherwise
-	 * @throws SearchException in case of IO errors on the index
+	 * @throws org.hibernate.search.SearchException in case of IO errors on the index
 	 */
 	boolean performOptimization(IndexWriter writer);
 

orm/src/main/java/org/hibernate/search/FullTextSession.java

@@ -53,7 +53,7 @@ public interface FullTextSession extends Session {
 	 * Indexation is batched per transaction: if a transaction is active, the operation
 	 * will not affect the index at least until commit.
 	 *
-	 * Any {@link EntityIndexingInterceptor} registered on the entity will be ignored:
+	 * Any {@link org.hibernate.search.indexes.interceptor.EntityIndexingInterceptor} registered on the entity will be ignored:
 	 * this method forces an index operation.
 	 *
 	 * @param entity The entity to index - must not be <code>null</code>.
@@ -72,7 +72,7 @@ public interface FullTextSession extends Session {
 	 * If <code>id == null</code> all indexed entities of this type and its indexed subclasses are deleted. In this
 	 * case this method behaves like {@link #purgeAll(Class)}.
 	 *
-	 * Any {@link EntityIndexingInterceptor} registered on the entity will be ignored:
+	 * Any {@link org.hibernate.search.indexes.interceptor.EntityIndexingInterceptor} registered on the entity will be ignored:
 	 * this method forces a purge operation.
 	 *
 	 * @param entityType The type of the entity to delete.
@@ -85,7 +85,7 @@ public interface FullTextSession extends Session {
 	/**
 	 * Remove all entities from of particular class and all its subclasses from the index.
 	 *
-	 * Any {@link EntityIndexingInterceptor} registered on the entity type will be ignored.
+	 * Any {@link org.hibernate.search.indexes.interceptor.EntityIndexingInterceptor} registered on the entity type will be ignored.
 	 *
 	 * @param entityType The class of the entities to remove.
 	 *
@@ -103,8 +103,8 @@ public interface FullTextSession extends Session {
 	 * or all indexed entity types.
 	 * Instances cannot be reused.
 	 *
-	 * Any {@link EntityIndexingInterceptor} registered on the entity types are applied: each instance will trigger
-	 * an {@link EntityIndexingInterceptor#onAdd(Object)} event from where you can customize the indexing operation.
+	 * Any {@link org.hibernate.search.indexes.interceptor.EntityIndexingInterceptor} registered on the entity types are applied: each instance will trigger
+	 * an {@link org.hibernate.search.indexes.interceptor.EntityIndexingInterceptor#onAdd(Object)} event from where you can customize the indexing operation.
 	 *
 	 * @param types optionally restrict the operation to selected types
 	 * @return a new MassIndexer

orm/src/test/java/org/hibernate/search/test/batchindexing/FetchSizeConfigurationTest.java

@@ -33,7 +33,7 @@
 import org.junit.runner.RunWith;
 
 /**
- * Verifies that {@link MassIndexer#idFetchSize(int)} is applied by checking for errors thrown by
+ * Verifies that {@link org.hibernate.search.MassIndexer#idFetchSize(int)} is applied by checking for errors thrown by
  * the JDBC Dialect. We use this approach especially as we want to make sure that using
  * {@link Integer#MIN_VALUE} is an acceptable option on MySQL as we suggest it on the documentation.
  *