Write SamplerConverter javadoc (#359)

* Write SamplerConverter javadoc

Hopefully this Javadoc helps people avoid the pitfall that I was caught
in

* Revert SamplerConverter style

Unfortunately "mvn formatter:format" overwrote the style of the
interface

* Add explanatory example to javadoc

---------

Co-authored-by: tpietzsch <[email protected]>

src/main/java/net/imglib2/converter/readwrite/SamplerConverter.java

@@ -11,13 +11,13 @@
  * %%
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions are met:
- * 
+ *
  * 1. Redistributions of source code must retain the above copyright notice,
  *    this list of conditions and the following disclaimer.
  * 2. Redistributions in binary form must reproduce the above copyright notice,
  *    this list of conditions and the following disclaimer in the documentation
  *    and/or other materials provided with the distribution.
- * 
+ *
  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
@@ -35,10 +35,37 @@
 package net.imglib2.converter.readwrite;
 
 import net.imglib2.Sampler;
+import net.imglib2.converter.Converters;
+import net.imglib2.type.Type;
 
 /**
- * TODO
- * 
+ * This interface converts a {@link Sampler Sampler<A>} into an instance
+ * of {@code B}, where {@code A} and {@code B} are typically {@link Type}s.
+ * <p>
+ * Its intended use is to create objects that <b>wrap</b> the provided
+ * {@code Sampler} itself instead of wrapping values obtained through the
+ * {@code Sampler}. In other words, <em>if the {@code Sampler} is pointed at a
+ * different object, <b>existing</b> objects returned by this
+ * {@code SamplerConverter} should point at it as well</em>.
+ * <p>
+ * {@code SamplerConverter}s are used in {@link Converters} to create on-the-fly
+ * converted images that are both readable and writable. For example, consider
+ * accessing a channel of an {@code ARGBType} image as {@code UnsignedByteType}.
+ * The converted image needs to provide converted samplers (e.g., {@code
+ * RandomAccess<UnsignedByteType>}) that "translate" to the samplers of the
+ * original image (e.g., {@code RandomAccess<ARGBType>}).
+ * <p>
+ * The converted {@code Sampler} returns an {@code UnsignedByteType} instance on
+ * {@code get()}. If {@code .setByte(10)} is called on that {@code
+ * UnsignedByteType} instance, that must be translated back to the underlying
+ * {@code ARGBType}. To achieve this, {@code SamplerConverter.convert(...)}
+ * creates a special {@code UnsignedByteType} instance which knows about a
+ * specific source sampler (e.g., {@code RandomAccess<ARGBType>}). When the
+ * {@code UnsignedByteType} instance is written to (or read from), it gets the
+ * current {@code ARGBType} from the source sampler and performs the conversion.
+ *
+ * @param <A> The type of values accessed by the {@link Sampler}.
+ * @param <B> The type of the value returned by this {@link SamplerConverter}.
  */
 public interface SamplerConverter< A, B >
 {