Add javadoc

src/main/java/net/imglib2/IterableInterval.java

@@ -64,12 +64,36 @@ public interface IterableInterval< T > extends IterableRealInterval< T >, Interv
 	@Override
 	Cursor< T > localizingCursor();
 
+	/**
+	 * Creates a {@link LocalizableSpliterator} over the elements of this {@code
+	 * IterableInterval}. The returned {@code Spliterator} iterates with optimal
+	 * speed without calculating the location at each iteration step.
+	 * Localization is performed on demand.
+	 *
+	 * @implSpec
+	 * The default implementation wraps a {@code Cursor} on the interval. The
+	 * created {@code Spliterator} reports {@link Spliterator#SIZED}, {@link
+	 * Spliterator#SUBSIZED},  {@link Spliterator#ORDERED} and {@link
+	 * Spliterator#NONNULL}.
+	 */
 	@Override
 	default LocalizableSpliterator< T > spliterator()
 	{
 		return new CursorSpliterator<>( cursor(),0, size(), Spliterator.ORDERED | Spliterator.NONNULL );
 	}
 
+	/**
+	 * Creates a {@link LocalizableSpliterator} over the elements of this {@code
+	 * IterableInterval}. The returned {@code Spliterator} calculates its
+	 * location at each iteration step. That is, localization is performed with
+	 * optimal speed.
+	 *
+	 * @implSpec
+	 * The default implementation wraps a {@link #localizingCursor() localizing}
+	 * {@code Cursor} on the interval. The created {@code Spliterator} reports
+	 * {@link Spliterator#SIZED}, {@link Spliterator#SUBSIZED},  {@link
+	 * Spliterator#ORDERED} and {@link Spliterator#NONNULL}.
+	 */
 	@Override
 	default LocalizableSpliterator< T > localizingSpliterator()
 	{

src/main/java/net/imglib2/IterableRealInterval.java

@@ -39,6 +39,7 @@
 import java.util.stream.StreamSupport;
 import net.imglib2.stream.RealCursorSpliterator;
 import net.imglib2.stream.RealLocalizableSpliterator;
+import net.imglib2.stream.Streams;
 
 /**
  * <p>
@@ -139,22 +140,70 @@ default java.util.Iterator< T > iterator() // TODO: fix places where it is not n
 		return cursor();
 	}
 
+	/**
+	 * Returns a sequential {@code Stream} over the elements of this {@code
+	 * IterableRealInterval}.
+	 * <p>
+	 * Note that the returned {@code Stream} gives access only to the values
+	 * of the elements, not their locations. To obtain a {@code Stream} that
+	 * includes locations, see {@link Streams#localizable}.
+	 *
+	 * @implSpec
+	 * The default implementation creates a sequential {@code Stream} from the
+	 * interval's {@link #spliterator()}.
+	 */
 	default Stream< T > stream()
 	{
 		return StreamSupport.stream( spliterator(), false );
 	}
 
+	/**
+	 * Returns a parallel {@code Stream} over the elements of this {@code
+	 * IterableRealInterval}.
+	 * <p>
+	 * Note that the returned {@code Stream} gives access only to the values
+	 * of the elements, not their locations. To obtain a {@code Stream} that
+	 * includes locations, see {@link Streams#localizable}.
+	 *
+	 * @implSpec
+	 * The default implementation creates a parallel {@code Stream} from the
+	 * interval's {@link #spliterator()}.
+	 */
 	default Stream< T > parallelStream()
 	{
 		return StreamSupport.stream( spliterator(), true );
 	}
 
+	/**
+	 * Creates a {@link RealLocalizableSpliterator} over the elements of this
+	 * {@code IterableRealInterval}. The returned {@code Spliterator} iterates
+	 * with optimal speed without calculating the location at each iteration
+	 * step. Localization is performed on demand.
+	 *
+	 * @implSpec
+	 * The default implementation wraps a {@code RealCursor} on the interval.
+	 * The created {@code Spliterator} reports {@link Spliterator#SIZED}, {@link
+	 * Spliterator#SUBSIZED},  {@link Spliterator#ORDERED} and {@link
+	 * Spliterator#NONNULL}.
+	 */
 	@Override
 	default RealLocalizableSpliterator< T > spliterator()
 	{
 		return new RealCursorSpliterator<>( cursor(),0, size(), Spliterator.ORDERED | Spliterator.NONNULL );
 	}
 
+	/**
+	 * Creates a {@link RealLocalizableSpliterator} over the elements of this
+	 * {@code IterableRealInterval}. The returned {@code Spliterator} calculates
+	 * its location at each iteration step. That is, localization is performed
+	 * with optimal speed.
+	 *
+	 * @implSpec
+	 * The default implementation wraps a {@link #localizingCursor() localizing}
+	 * {@code RealCursor} on the interval. The created {@code Spliterator}
+	 * reports {@link Spliterator#SIZED}, {@link Spliterator#SUBSIZED},  {@link
+	 * Spliterator#ORDERED} and {@link Spliterator#NONNULL}.
+	 */
 	default RealLocalizableSpliterator< T > localizingSpliterator()
 	{
 		return new RealCursorSpliterator<>( localizingCursor(), 0, size(), Spliterator.ORDERED | Spliterator.NONNULL );

src/main/java/net/imglib2/LocalizableSampler.java

@@ -1,5 +1,12 @@
 package net.imglib2;
 
+/**
+ * Combination of {@code Localizable} and {@code Sampler} interfaces. In
+ * general, it is preferable to use {@code Localizable & Sampler<T>} where
+ * possible.
+ *
+ * @param <T> pixel type
+ */
 public interface LocalizableSampler< T > extends Localizable, RealLocalizableSampler< T >
 {
 	@Override

src/main/java/net/imglib2/RealLocalizableSampler.java

@@ -1,5 +1,12 @@
 package net.imglib2;
 
+/**
+ * Combination of {@code RealLocalizable} and {@code Sampler} interfaces. In
+ * general, it is preferable to use {@code RealLocalizable & Sampler<T>} where
+ * possible.
+ *
+ * @param <T> pixel type
+ */
 public interface RealLocalizableSampler< T > extends RealLocalizable, Sampler< T >
 {
 	@Override

src/main/java/net/imglib2/img/array/ArrayLocalizingSpliterator.java

@@ -41,6 +41,12 @@
 import net.imglib2.type.NativeType;
 import net.imglib2.util.IntervalIndexer;
 
+/**
+ * LocalizableSpliterator for ArrayImg.
+ * Keeps track of location on every step.
+ *
+ * @param <T> pixel type
+ */
 class ArrayLocalizingSpliterator< T extends NativeType< T > > extends AbstractLocalizableInt implements LocalizableSpliterator< T >
 {
 	private final ArrayImg< T, ? > img;

src/main/java/net/imglib2/img/array/ArraySpliterator.java

@@ -42,6 +42,12 @@
 import net.imglib2.type.NativeType;
 import net.imglib2.util.IntervalIndexer;
 
+/**
+ * LocalizableSpliterator for ArrayImg.
+ * Localizes on demand.
+ *
+ * @param <T> pixel type
+ */
 class ArraySpliterator< T extends NativeType< T > > implements LocalizableSpliterator< T >
 {
 	private final ArrayImg< T, ? > img;

src/main/java/net/imglib2/img/cell/CellSpliterator.java

@@ -43,7 +43,10 @@
 import net.imglib2.type.NativeType;
 
 /**
- * Spliterator for {@link CellImg}.
+ * LocalizableSpliterator for {@link CellImg}.
+ * Localizes on demand.
+ *
+ * @param <T> pixel type
  */
 class CellSpliterator< T extends NativeType< T >, C extends Cell< ? > > implements LocalizableSpliterator< T >
 {

src/main/java/net/imglib2/img/planar/PlanarSpliterator.java

@@ -41,6 +41,12 @@
 import net.imglib2.type.Index;
 import net.imglib2.type.NativeType;
 
+/**
+ * LocalizableSpliterator for {@link PlanarImg}.
+ * Localizes on demand.
+ *
+ * @param <T> pixel type
+ */
 class PlanarSpliterator< T extends NativeType< T > > implements LocalizableSpliterator< T >, PlanarImg.PlanarContainerSampler
 {
 	private final PlanarImg< T, ? > img;

src/main/java/net/imglib2/stream/LocalizableSamplerWrapper.java

@@ -6,10 +6,25 @@
 import net.imglib2.Positionable;
 import net.imglib2.RealPositionable;
 
+/**
+ * Wraps {@link LocalizableSpliterator} as {@code Spliterator<LocalizableSampler<T>>}.
+ * <p>
+ * Concretely, it implements {@code LocalizableSampler}, forwarding all methods
+ * to the wrapped {@code LocalizableSpliterator}. And passes itself as a proxy
+ * to the {@code Consumer} in {@link #tryAdvance} and {@link #forEachRemaining}.
+ *
+ * @param <T> pixel type
+ */
 class LocalizableSamplerWrapper< T > implements Spliterator< LocalizableSampler< T > >, LocalizableSampler< T >
 {
 	private final LocalizableSpliterator< T > delegate;
 
+	/**
+	 * Wrap the given {@code delegate} as {@code Spliterator<LocalizableSampler<T>>}.
+	 *
+	 * @param delegate
+	 * 		spliterator to wrap
+	 */
 	LocalizableSamplerWrapper( final LocalizableSpliterator< T > delegate )
 	{
 		this.delegate = delegate;

src/main/java/net/imglib2/stream/LocalizableSpliterator.java

@@ -1,7 +1,36 @@
 package net.imglib2.stream;
 
+import net.imglib2.IterableInterval;
 import net.imglib2.Localizable;
 
+/**
+ * A {@code Spliterator<T>} which is Localizable similar to a Cursor.
+ * <p>
+ * The location of the Spliterator reflects the location of the element passed
+ * to the {@code Consumer} in {@link #tryAdvance} or {@link #forEachRemaining}
+ * (at the time the element is passed, and until the next element is passed).
+ * <p>
+ * Similar to {@code Cursor}, {@code LocalizableSpliterator} usually
+ * comes in two flavors:
+ * <ul>
+ *     <li>{@link IterableInterval#spliterator()} computes location only on demand, and</li>
+ *     <li>{@link IterableInterval#localizingSpliterator()} preemptively tracks location on every step.</li>
+ * </ul>
+ * (Which one is more efficient depends on how often location is actually needed.)
+ * <p>
+ * To make the {@code Localizable} property available in a {@code Stream}, use
+ * the {@link Streams} utility class to create {@code
+ * Stream<LocalizableSampler<T>>} (which internally wraps {@code
+ * LocalizableSpliterator}).
+ * <p>
+ * Corresponding to the {@code LocalizableSpliterator} flavors,
+ * <ul>
+ *     <li>{@link Streams#localizable(IterableInterval)} computes element location only on demand, and
+ *     <li>{@link Streams#localizing(IterableInterval)} tracks location on every step.</li>
+ * </ul>
+ *
+ * @param <T> pixel type
+ */
 public interface LocalizableSpliterator< T > extends RealLocalizableSpliterator< T >, Localizable
 {
 	@Override

src/main/java/net/imglib2/stream/RealLocalizableSamplerWrapper.java

@@ -5,10 +5,25 @@
 import net.imglib2.RealLocalizableSampler;
 import net.imglib2.RealPositionable;
 
+/**
+ * Wraps {@link RealLocalizableSpliterator} as {@code Spliterator<RealLocalizableSampler<T>>}.
+ * <p>
+ * Concretely, it implements {@code RealLocalizableSampler}, forwarding all methods
+ * to the wrapped {@code RealLocalizableSpliterator}. And passes itself as a proxy
+ * to the {@code Consumer} in {@link #tryAdvance} and {@link #forEachRemaining}.
+ *
+ * @param <T> pixel type
+ */
 class RealLocalizableSamplerWrapper< T > implements Spliterator< RealLocalizableSampler< T > >, RealLocalizableSampler< T >
 {
 	private final RealLocalizableSpliterator< T > delegate;
 
+	/**
+	 * Wrap the given {@code delegate} as {@code Spliterator<RealLocalizableSampler<T>>}.
+	 *
+	 * @param delegate
+	 * 		spliterator to wrap
+	 */
 	RealLocalizableSamplerWrapper( final RealLocalizableSpliterator< T > delegate )
 	{
 		this.delegate = delegate;

src/main/java/net/imglib2/stream/RealLocalizableSpliterator.java

@@ -1,9 +1,38 @@
 package net.imglib2.stream;
 
 import java.util.Spliterator;
+import net.imglib2.IterableRealInterval;
 import net.imglib2.RealLocalizable;
 import net.imglib2.Sampler;
 
+/**
+ * A {@code Spliterator<T>} which is Localizable similar to a Cursor.
+ * <p>
+ * The location of the Spliterator reflects the location of the element passed
+ * to the {@code Consumer} in {@link #tryAdvance} or {@link #forEachRemaining}
+ * (at the time the element is passed, and until the next element is passed).
+ * <p>
+ * Similar to {@code RealCursor}, {@code RealLocalizableSpliterator} usually
+ * comes in two flavors:
+ * <ul>
+ *     <li>{@link IterableRealInterval#spliterator()} computes location only on demand, and</li>
+ *     <li>{@link IterableRealInterval#localizingSpliterator()} preemptively tracks location on every step.</li>
+ * </ul>
+ * (Which one is more efficient depends on how often location is actually needed.)
+ * <p>
+ * To make the {@code RealLocalizable} property available in a {@code Stream},
+ * use the {@link Streams} utility class to create {@code
+ * Stream<RealLocalizableSampler<T>>} (which internally wraps {@code
+ * RealLocalizableSpliterator}).
+ * <p>
+ * Corresponding to the {@code RealLocalizableSpliterator} flavors,
+ * <ul>
+ *     <li>{@link Streams#localizable(IterableRealInterval)} computes element location only on demand, and
+ *     <li>{@link Streams#localizing(IterableRealInterval)} tracks location on every step.</li>
+ * </ul>
+ *
+ * @param <T> pixel type
+ */
 public interface RealLocalizableSpliterator< T > extends Spliterator< T >, RealLocalizable, Sampler< T >
 {
 	@Override