Add explanatory example to javadoc

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

@@ -35,17 +35,34 @@
 package net.imglib2.converter.readwrite;
 
 import net.imglib2.Sampler;
+import net.imglib2.converter.Converters;
+import net.imglib2.type.Type;
 
 /**
- * This interface converts a {@link Sampler} into an instance of a different
- * type.
+ * 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>
+ * <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}.