Javadoc corrections and formatting

10 files changed, 105 insertions, 65 deletions

diff --git a/docs/javadoc/com/davemorrissey/labs/subscaleview/decoder/DecoderFactory.html b/docs/javadoc/com/davemorrissey/labs/subscaleview/decoder/DecoderFactory.html
index 3b0d234..138a76a 100644
--- a/docs/javadoc/com/davemorrissey/labs/subscaleview/decoder/DecoderFactory.html
+++ b/docs/javadoc/com/davemorrissey/labs/subscaleview/decoder/DecoderFactory.html
@@ -108,7 +108,7 @@ var activeTableTab = "activeTableTab";
 <hr>
 <br>
 <pre>public interface <span class="typeNameLabel">DecoderFactory&lt;T&gt;</span></pre>
-<div class="block">Interface for decoder (and region decoder) factories.</div>
+<div class="block">Interface for <a href="../../../../../com/davemorrissey/labs/subscaleview/decoder/ImageDecoder.html" title="interface in com.davemorrissey.labs.subscaleview.decoder"><code>ImageDecoder</code></a> and <a href="../../../../../com/davemorrissey/labs/subscaleview/decoder/ImageRegionDecoder.html" title="interface in com.davemorrissey.labs.subscaleview.decoder"><code>ImageRegionDecoder</code></a> factories.</div>
 </li>
 </ul>
 </div>
diff --git a/docs/javadoc/com/davemorrissey/labs/subscaleview/decoder/ImageDecoder.html b/docs/javadoc/com/davemorrissey/labs/subscaleview/decoder/ImageDecoder.html
index bb5dc05..afd253a 100644
--- a/docs/javadoc/com/davemorrissey/labs/subscaleview/decoder/ImageDecoder.html
+++ b/docs/javadoc/com/davemorrissey/labs/subscaleview/decoder/ImageDecoder.html
@@ -104,7 +104,7 @@ var activeTableTab = "activeTableTab";
 <hr>
 <br>
 <pre>public interface <span class="typeNameLabel">ImageDecoder</span></pre>
-<div class="block">Interface for image decoding classes, allowing the default <code>BitmapRegionDecoder</code>
+<div class="block">Interface for image decoding classes, allowing the default <code>BitmapFactory</code>
  based on the Skia library to be replaced with a custom class.</div>
 </li>
 </ul>
@@ -155,19 +155,21 @@ var activeTableTab = "activeTableTab";
 <pre>android.graphics.Bitmap&nbsp;decode(android.content.Context&nbsp;context,
                                android.net.Uri&nbsp;uri)
                         throws java.lang.Exception</pre>
-<div class="block">Decode an image. When possible, initial setup work once in this method. This method
- must return the dimensions of the image. The URI can be in one of the following formats:
- File: file:///scard/picture.jpg
- Asset: file:///android_asset/picture.png
- Resource: android.resource://com.example.app/drawable/picture</div>
+<div class="block">Decode an image. The URI can be in one of the following formats:
+ <br>
+ File: <code>file:///scard/picture.jpg</code>
+ <br>
+ Asset: <code>file:///android_asset/picture.png</code>
+ <br>
+ Resource: <code>android.resource://com.example.app/drawable/picture</code></div>
 <dl>
 <dt><span class="paramLabel">Parameters:</span></dt>
-<dd><code>context</code> - Application context. A reference may be held, but must be cleared on recycle.</dd>
-<dd><code>uri</code> - URI of the image.</dd>
+<dd><code>context</code> - Application context</dd>
+<dd><code>uri</code> - URI of the image</dd>
 <dt><span class="returnLabel">Returns:</span></dt>
-<dd>Dimensions of the image.</dd>
+<dd>the decoded bitmap</dd>
 <dt><span class="throwsLabel">Throws:</span></dt>
-<dd><code>java.lang.Exception</code> - if initialisation fails.</dd>
+<dd><code>java.lang.Exception</code> - if decoding fails.</dd>
 </dl>
 </li>
 </ul>
diff --git a/docs/javadoc/com/davemorrissey/labs/subscaleview/decoder/ImageRegionDecoder.html b/docs/javadoc/com/davemorrissey/labs/subscaleview/decoder/ImageRegionDecoder.html
index d1e83e4..2a5fff7 100644
--- a/docs/javadoc/com/davemorrissey/labs/subscaleview/decoder/ImageRegionDecoder.html
+++ b/docs/javadoc/com/davemorrissey/labs/subscaleview/decoder/ImageRegionDecoder.html
@@ -128,7 +128,8 @@ var activeTableTab = "activeTableTab";
 <td class="colFirst"><code>android.graphics.Bitmap</code></td>
 <td class="colLast"><code><span class="memberNameLink"><a href="../../../../../com/davemorrissey/labs/subscaleview/decoder/ImageRegionDecoder.html#decodeRegion-android.graphics.Rect-int-">decodeRegion</a></span>(android.graphics.Rect&nbsp;sRect,
             int&nbsp;sampleSize)</code>
-<div class="block">Decode a region of the image with the given sample size.</div>
+<div class="block">
+ Decode a region of the image with the given sample size.</div>
 </td>
 </tr>
 <tr id="i1" class="rowColor">
@@ -174,11 +175,14 @@ var activeTableTab = "activeTableTab";
 <pre>android.graphics.Point&nbsp;init(android.content.Context&nbsp;context,
                             android.net.Uri&nbsp;uri)
                      throws java.lang.Exception</pre>
-<div class="block">Initialise the decoder. When possible, initial setup work once in this method. This method
- must return the dimensions of the image. The URI can be in one of the following formats:
- File: file:///scard/picture.jpg
- Asset: file:///android_asset/picture.png
- Resource: android.resource://com.example.app/drawable/picture</div>
+<div class="block">Initialise the decoder. When possible, perform initial setup work once in this method. The
+ dimensions of the image must be returned. The URI can be in one of the following formats:
+ <br>
+ File: <code>file:///scard/picture.jpg</code>
+ <br>
+ Asset: <code>file:///android_asset/picture.png</code>
+ <br>
+ Resource: <code>android.resource://com.example.app/drawable/picture</code></div>
 <dl>
 <dt><span class="paramLabel">Parameters:</span></dt>
 <dd><code>context</code> - Application context. A reference may be held, but must be cleared on recycle.</dd>
@@ -198,10 +202,17 @@ var activeTableTab = "activeTableTab";
 <h4>decodeRegion</h4>
 <pre>android.graphics.Bitmap&nbsp;decodeRegion(android.graphics.Rect&nbsp;sRect,
                                      int&nbsp;sampleSize)</pre>
-<div class="block">Decode a region of the image with the given sample size. This method is called off the UI thread so it can safely
- load the image on the current thread. It is called from an <code>AsyncTask</code> running in a single
- threaded executor, and while a synchronization lock is held on this object, so will never be called concurrently
- even if the decoder implementation supports it.</div>
+<div class="block"><p>
+ Decode a region of the image with the given sample size. This method is called off the UI
+ thread so it can safely load the image on the current thread. It is called from
+ <code>AsyncTask</code>s running in an executor that may have multiple threads, so
+ implementations must be thread safe. Adding <code>synchronized</code> to the method signature
+ is the simplest way to achieve this, but bear in mind the <a href="../../../../../com/davemorrissey/labs/subscaleview/decoder/ImageRegionDecoder.html#recycle--"><code>recycle()</code></a> method can be
+ called concurrently.
+ </p><p>
+ See <a href="../../../../../com/davemorrissey/labs/subscaleview/decoder/SkiaImageRegionDecoder.html" title="class in com.davemorrissey.labs.subscaleview.decoder"><code>SkiaImageRegionDecoder</code></a> and <a href="../../../../../com/davemorrissey/labs/subscaleview/decoder/SkiaPooledImageRegionDecoder.html" title="class in com.davemorrissey.labs.subscaleview.decoder"><code>SkiaPooledImageRegionDecoder</code></a> for examples of
+ internal locking and synchronization.
+ </p></div>
 <dl>
 <dt><span class="paramLabel">Parameters:</span></dt>
 <dd><code>sRect</code> - Source image rectangle to decode.</dd>
diff --git a/docs/javadoc/com/davemorrissey/labs/subscaleview/decoder/SkiaImageDecoder.html b/docs/javadoc/com/davemorrissey/labs/subscaleview/decoder/SkiaImageDecoder.html
index 23f03e0..3e3314f 100644
--- a/docs/javadoc/com/davemorrissey/labs/subscaleview/decoder/SkiaImageDecoder.html
+++ b/docs/javadoc/com/davemorrissey/labs/subscaleview/decoder/SkiaImageDecoder.html
@@ -221,21 +221,23 @@ implements <a href="../../../../../com/davemorrissey/labs/subscaleview/decoder/I
                                       android.net.Uri&nbsp;uri)
                                throws java.lang.Exception</pre>
 <div class="block"><span class="descfrmTypeLabel">Description copied from interface:&nbsp;<code><a href="../../../../../com/davemorrissey/labs/subscaleview/decoder/ImageDecoder.html#decode-android.content.Context-android.net.Uri-">ImageDecoder</a></code></span></div>
-<div class="block">Decode an image. When possible, initial setup work once in this method. This method
- must return the dimensions of the image. The URI can be in one of the following formats:
- File: file:///scard/picture.jpg
- Asset: file:///android_asset/picture.png
- Resource: android.resource://com.example.app/drawable/picture</div>
+<div class="block">Decode an image. The URI can be in one of the following formats:
+ <br>
+ File: <code>file:///scard/picture.jpg</code>
+ <br>
+ Asset: <code>file:///android_asset/picture.png</code>
+ <br>
+ Resource: <code>android.resource://com.example.app/drawable/picture</code></div>
 <dl>
 <dt><span class="overrideSpecifyLabel">Specified by:</span></dt>
 <dd><code><a href="../../../../../com/davemorrissey/labs/subscaleview/decoder/ImageDecoder.html#decode-android.content.Context-android.net.Uri-">decode</a></code>&nbsp;in interface&nbsp;<code><a href="../../../../../com/davemorrissey/labs/subscaleview/decoder/ImageDecoder.html" title="interface in com.davemorrissey.labs.subscaleview.decoder">ImageDecoder</a></code></dd>
 <dt><span class="paramLabel">Parameters:</span></dt>
-<dd><code>context</code> - Application context. A reference may be held, but must be cleared on recycle.</dd>
-<dd><code>uri</code> - URI of the image.</dd>
+<dd><code>context</code> - Application context</dd>
+<dd><code>uri</code> - URI of the image</dd>
 <dt><span class="returnLabel">Returns:</span></dt>
-<dd>Dimensions of the image.</dd>
+<dd>the decoded bitmap</dd>
 <dt><span class="throwsLabel">Throws:</span></dt>
-<dd><code>java.lang.Exception</code> - if initialisation fails.</dd>
+<dd><code>java.lang.Exception</code> - if decoding fails.</dd>
 </dl>
 </li>
 </ul>
diff --git a/docs/javadoc/com/davemorrissey/labs/subscaleview/decoder/SkiaImageRegionDecoder.html b/docs/javadoc/com/davemorrissey/labs/subscaleview/decoder/SkiaImageRegionDecoder.html
index b069121..7c3ffef 100644
--- a/docs/javadoc/com/davemorrissey/labs/subscaleview/decoder/SkiaImageRegionDecoder.html
+++ b/docs/javadoc/com/davemorrissey/labs/subscaleview/decoder/SkiaImageRegionDecoder.html
@@ -165,7 +165,8 @@ implements <a href="../../../../../com/davemorrissey/labs/subscaleview/decoder/I
 <td class="colFirst"><code>android.graphics.Bitmap</code></td>
 <td class="colLast"><code><span class="memberNameLink"><a href="../../../../../com/davemorrissey/labs/subscaleview/decoder/SkiaImageRegionDecoder.html#decodeRegion-android.graphics.Rect-int-">decodeRegion</a></span>(android.graphics.Rect&nbsp;sRect,
             int&nbsp;sampleSize)</code>
-<div class="block">Decode a region of the image with the given sample size.</div>
+<div class="block">
+ Decode a region of the image with the given sample size.</div>
 </td>
 </tr>
 <tr id="i1" class="rowColor">
@@ -245,11 +246,14 @@ implements <a href="../../../../../com/davemorrissey/labs/subscaleview/decoder/I
                                    android.net.Uri&nbsp;uri)
                             throws java.lang.Exception</pre>
 <div class="block"><span class="descfrmTypeLabel">Description copied from interface:&nbsp;<code><a href="../../../../../com/davemorrissey/labs/subscaleview/decoder/ImageRegionDecoder.html#init-android.content.Context-android.net.Uri-">ImageRegionDecoder</a></code></span></div>
-<div class="block">Initialise the decoder. When possible, initial setup work once in this method. This method
- must return the dimensions of the image. The URI can be in one of the following formats:
- File: file:///scard/picture.jpg
- Asset: file:///android_asset/picture.png
- Resource: android.resource://com.example.app/drawable/picture</div>
+<div class="block">Initialise the decoder. When possible, perform initial setup work once in this method. The
+ dimensions of the image must be returned. The URI can be in one of the following formats:
+ <br>
+ File: <code>file:///scard/picture.jpg</code>
+ <br>
+ Asset: <code>file:///android_asset/picture.png</code>
+ <br>
+ Resource: <code>android.resource://com.example.app/drawable/picture</code></div>
 <dl>
 <dt><span class="overrideSpecifyLabel">Specified by:</span></dt>
 <dd><code><a href="../../../../../com/davemorrissey/labs/subscaleview/decoder/ImageRegionDecoder.html#init-android.content.Context-android.net.Uri-">init</a></code>&nbsp;in interface&nbsp;<code><a href="../../../../../com/davemorrissey/labs/subscaleview/decoder/ImageRegionDecoder.html" title="interface in com.davemorrissey.labs.subscaleview.decoder">ImageRegionDecoder</a></code></dd>
@@ -272,10 +276,17 @@ implements <a href="../../../../../com/davemorrissey/labs/subscaleview/decoder/I
 <pre>public&nbsp;android.graphics.Bitmap&nbsp;decodeRegion(android.graphics.Rect&nbsp;sRect,
                                             int&nbsp;sampleSize)</pre>
 <div class="block"><span class="descfrmTypeLabel">Description copied from interface:&nbsp;<code><a href="../../../../../com/davemorrissey/labs/subscaleview/decoder/ImageRegionDecoder.html#decodeRegion-android.graphics.Rect-int-">ImageRegionDecoder</a></code></span></div>
-<div class="block">Decode a region of the image with the given sample size. This method is called off the UI thread so it can safely
- load the image on the current thread. It is called from an <code>AsyncTask</code> running in a single
- threaded executor, and while a synchronization lock is held on this object, so will never be called concurrently
- even if the decoder implementation supports it.</div>
+<div class="block"><p>
+ Decode a region of the image with the given sample size. This method is called off the UI
+ thread so it can safely load the image on the current thread. It is called from
+ <code>AsyncTask</code>s running in an executor that may have multiple threads, so
+ implementations must be thread safe. Adding <code>synchronized</code> to the method signature
+ is the simplest way to achieve this, but bear in mind the <a href="../../../../../com/davemorrissey/labs/subscaleview/decoder/ImageRegionDecoder.html#recycle--"><code>ImageRegionDecoder.recycle()</code></a> method can be
+ called concurrently.
+ </p><p>
+ See <a href="../../../../../com/davemorrissey/labs/subscaleview/decoder/SkiaImageRegionDecoder.html" title="class in com.davemorrissey.labs.subscaleview.decoder"><code>SkiaImageRegionDecoder</code></a> and <a href="../../../../../com/davemorrissey/labs/subscaleview/decoder/SkiaPooledImageRegionDecoder.html" title="class in com.davemorrissey.labs.subscaleview.decoder"><code>SkiaPooledImageRegionDecoder</code></a> for examples of
+ internal locking and synchronization.
+ </p></div>
 <dl>
 <dt><span class="overrideSpecifyLabel">Specified by:</span></dt>
 <dd><code><a href="../../../../../com/davemorrissey/labs/subscaleview/decoder/ImageRegionDecoder.html#decodeRegion-android.graphics.Rect-int-">decodeRegion</a></code>&nbsp;in interface&nbsp;<code><a href="../../../../../com/davemorrissey/labs/subscaleview/decoder/ImageRegionDecoder.html" title="interface in com.davemorrissey.labs.subscaleview.decoder">ImageRegionDecoder</a></code></dd>
diff --git a/docs/javadoc/com/davemorrissey/labs/subscaleview/decoder/package-summary.html b/docs/javadoc/com/davemorrissey/labs/subscaleview/decoder/package-summary.html
index ce29132..8805372 100644
--- a/docs/javadoc/com/davemorrissey/labs/subscaleview/decoder/package-summary.html
+++ b/docs/javadoc/com/davemorrissey/labs/subscaleview/decoder/package-summary.html
@@ -83,13 +83,13 @@
 <tr class="altColor">
 <td class="colFirst"><a href="../../../../../com/davemorrissey/labs/subscaleview/decoder/DecoderFactory.html" title="interface in com.davemorrissey.labs.subscaleview.decoder">DecoderFactory</a>&lt;T&gt;</td>
 <td class="colLast">
-<div class="block">Interface for decoder (and region decoder) factories.</div>
+<div class="block">Interface for <a href="../../../../../com/davemorrissey/labs/subscaleview/decoder/ImageDecoder.html" title="interface in com.davemorrissey.labs.subscaleview.decoder"><code>ImageDecoder</code></a> and <a href="../../../../../com/davemorrissey/labs/subscaleview/decoder/ImageRegionDecoder.html" title="interface in com.davemorrissey.labs.subscaleview.decoder"><code>ImageRegionDecoder</code></a> factories.</div>
 </td>
 </tr>
 <tr class="rowColor">
 <td class="colFirst"><a href="../../../../../com/davemorrissey/labs/subscaleview/decoder/ImageDecoder.html" title="interface in com.davemorrissey.labs.subscaleview.decoder">ImageDecoder</a></td>
 <td class="colLast">
-<div class="block">Interface for image decoding classes, allowing the default <code>BitmapRegionDecoder</code>
+<div class="block">Interface for image decoding classes, allowing the default <code>BitmapFactory</code>
  based on the Skia library to be replaced with a custom class.</div>
 </td>
 </tr>
diff --git a/docs/javadoc/index-all.html b/docs/javadoc/index-all.html
index 0c59348..eb270eb 100644
--- a/docs/javadoc/index-all.html
+++ b/docs/javadoc/index-all.html
@@ -143,7 +143,8 @@
 <dd>&nbsp;</dd>
 <dt><span class="memberNameLink"><a href="com/davemorrissey/labs/subscaleview/decoder/ImageRegionDecoder.html#decodeRegion-android.graphics.Rect-int-">decodeRegion(Rect, int)</a></span> - Method in interface com.davemorrissey.labs.subscaleview.decoder.<a href="com/davemorrissey/labs/subscaleview/decoder/ImageRegionDecoder.html" title="interface in com.davemorrissey.labs.subscaleview.decoder">ImageRegionDecoder</a></dt>
 <dd>
-<div class="block">Decode a region of the image with the given sample size.</div>
+<div class="block">
+ Decode a region of the image with the given sample size.</div>
 </dd>
 <dt><span class="memberNameLink"><a href="com/davemorrissey/labs/subscaleview/decoder/SkiaImageRegionDecoder.html#decodeRegion-android.graphics.Rect-int-">decodeRegion(Rect, int)</a></span> - Method in class com.davemorrissey.labs.subscaleview.decoder.<a href="com/davemorrissey/labs/subscaleview/decoder/SkiaImageRegionDecoder.html" title="class in com.davemorrissey.labs.subscaleview.decoder">SkiaImageRegionDecoder</a></dt>
 <dd>&nbsp;</dd>
@@ -154,7 +155,7 @@
 </dd>
 <dt><a href="com/davemorrissey/labs/subscaleview/decoder/DecoderFactory.html" title="interface in com.davemorrissey.labs.subscaleview.decoder"><span class="typeNameLink">DecoderFactory</span></a>&lt;<a href="com/davemorrissey/labs/subscaleview/decoder/DecoderFactory.html" title="type parameter in DecoderFactory">T</a>&gt; - Interface in <a href="com/davemorrissey/labs/subscaleview/decoder/package-summary.html">com.davemorrissey.labs.subscaleview.decoder</a></dt>
 <dd>
-<div class="block">Interface for decoder (and region decoder) factories.</div>
+<div class="block">Interface for <a href="com/davemorrissey/labs/subscaleview/decoder/ImageDecoder.html" title="interface in com.davemorrissey.labs.subscaleview.decoder"><code>ImageDecoder</code></a> and <a href="com/davemorrissey/labs/subscaleview/decoder/ImageRegionDecoder.html" title="interface in com.davemorrissey.labs.subscaleview.decoder"><code>ImageRegionDecoder</code></a> factories.</div>
 </dd>
 <dt><span class="memberNameLink"><a href="com/davemorrissey/labs/subscaleview/SubsamplingScaleImageView.DefaultOnAnimationEventListener.html#DefaultOnAnimationEventListener--">DefaultOnAnimationEventListener()</a></span> - Constructor for class com.davemorrissey.labs.subscaleview.<a href="com/davemorrissey/labs/subscaleview/SubsamplingScaleImageView.DefaultOnAnimationEventListener.html" title="class in com.davemorrissey.labs.subscaleview">SubsamplingScaleImageView.DefaultOnAnimationEventListener</a></dt>
 <dd>&nbsp;</dd>
@@ -268,7 +269,7 @@
 <dl>
 <dt><a href="com/davemorrissey/labs/subscaleview/decoder/ImageDecoder.html" title="interface in com.davemorrissey.labs.subscaleview.decoder"><span class="typeNameLink">ImageDecoder</span></a> - Interface in <a href="com/davemorrissey/labs/subscaleview/decoder/package-summary.html">com.davemorrissey.labs.subscaleview.decoder</a></dt>
 <dd>
-<div class="block">Interface for image decoding classes, allowing the default <code>BitmapRegionDecoder</code>
+<div class="block">Interface for image decoding classes, allowing the default <code>BitmapFactory</code>
  based on the Skia library to be replaced with a custom class.</div>
 </dd>
 <dt><a href="com/davemorrissey/labs/subscaleview/decoder/ImageRegionDecoder.html" title="interface in com.davemorrissey.labs.subscaleview.decoder"><span class="typeNameLink">ImageRegionDecoder</span></a> - Interface in <a href="com/davemorrissey/labs/subscaleview/decoder/package-summary.html">com.davemorrissey.labs.subscaleview.decoder</a></dt>
diff --git a/library/src/main/java/com/davemorrissey/labs/subscaleview/decoder/DecoderFactory.java b/library/src/main/java/com/davemorrissey/labs/subscaleview/decoder/DecoderFactory.java
index 8bb5c16..e2b5ce6 100644
--- a/library/src/main/java/com/davemorrissey/labs/subscaleview/decoder/DecoderFactory.java
+++ b/library/src/main/java/com/davemorrissey/labs/subscaleview/decoder/DecoderFactory.java
@@ -3,7 +3,7 @@ package com.davemorrissey.labs.subscaleview.decoder;
 import java.lang.reflect.InvocationTargetException;
 
 /**
- * Interface for decoder (and region decoder) factories.
+ * Interface for {@link ImageDecoder} and {@link ImageRegionDecoder} factories.
  * @param <T> the class of decoder that will be produced.
  */
 public interface DecoderFactory<T> {
diff --git a/library/src/main/java/com/davemorrissey/labs/subscaleview/decoder/ImageDecoder.java b/library/src/main/java/com/davemorrissey/labs/subscaleview/decoder/ImageDecoder.java
index 371b87d..c403b7e 100644
--- a/library/src/main/java/com/davemorrissey/labs/subscaleview/decoder/ImageDecoder.java
+++ b/library/src/main/java/com/davemorrissey/labs/subscaleview/decoder/ImageDecoder.java
@@ -7,21 +7,24 @@ import android.graphics.Rect;
 import android.net.Uri;
 
 /**
- * Interface for image decoding classes, allowing the default {@link android.graphics.BitmapRegionDecoder}
+ * Interface for image decoding classes, allowing the default {@link android.graphics.BitmapFactory}
  * based on the Skia library to be replaced with a custom class.
  */
 public interface ImageDecoder {
 
     /**
-     * Decode an image. When possible, initial setup work once in this method. This method
-     * must return the dimensions of the image. The URI can be in one of the following formats:
-     * File: file:///scard/picture.jpg
-     * Asset: file:///android_asset/picture.png
-     * Resource: android.resource://com.example.app/drawable/picture
-     * @param context Application context. A reference may be held, but must be cleared on recycle.
-     * @param uri URI of the image.
-     * @return Dimensions of the image.
-     * @throws Exception if initialisation fails.
+     * Decode an image. The URI can be in one of the following formats:
+     * <br>
+     * File: <code>file:///scard/picture.jpg</code>
+     * <br>
+     * Asset: <code>file:///android_asset/picture.png</code>
+     * <br>
+     * Resource: <code>android.resource://com.example.app/drawable/picture</code>
+     *
+     * @param context Application context
+     * @param uri URI of the image
+     * @return the decoded bitmap
+     * @throws Exception if decoding fails.
      */
     Bitmap decode(Context context, Uri uri) throws Exception;
 
diff --git a/library/src/main/java/com/davemorrissey/labs/subscaleview/decoder/ImageRegionDecoder.java b/library/src/main/java/com/davemorrissey/labs/subscaleview/decoder/ImageRegionDecoder.java
index 347a6f4..22ee955 100644
--- a/library/src/main/java/com/davemorrissey/labs/subscaleview/decoder/ImageRegionDecoder.java
+++ b/library/src/main/java/com/davemorrissey/labs/subscaleview/decoder/ImageRegionDecoder.java
@@ -13,11 +13,14 @@ import android.net.Uri;
 public interface ImageRegionDecoder {
 
     /**
-     * Initialise the decoder. When possible, initial setup work once in this method. This method
-     * must return the dimensions of the image. The URI can be in one of the following formats:
-     * File: file:///scard/picture.jpg
-     * Asset: file:///android_asset/picture.png
-     * Resource: android.resource://com.example.app/drawable/picture
+     * Initialise the decoder. When possible, perform initial setup work once in this method. The
+     * dimensions of the image must be returned. The URI can be in one of the following formats:
+     * <br>
+     * File: <code>file:///scard/picture.jpg</code>
+     * <br>
+     * Asset: <code>file:///android_asset/picture.png</code>
+     * <br>
+     * Resource: <code>android.resource://com.example.app/drawable/picture</code>
      * @param context Application context. A reference may be held, but must be cleared on recycle.
      * @param uri URI of the image.
      * @return Dimensions of the image.
@@ -26,10 +29,17 @@ public interface ImageRegionDecoder {
     Point init(Context context, Uri uri) throws Exception;
 
     /**
-     * Decode a region of the image with the given sample size. This method is called off the UI thread so it can safely
-     * load the image on the current thread. It is called from an {@link android.os.AsyncTask} running in a single
-     * threaded executor, and while a synchronization lock is held on this object, so will never be called concurrently
-     * even if the decoder implementation supports it.
+     * <p>
+     * Decode a region of the image with the given sample size. This method is called off the UI
+     * thread so it can safely load the image on the current thread. It is called from
+     * {@link android.os.AsyncTask}s running in an executor that may have multiple threads, so
+     * implementations must be thread safe. Adding <code>synchronized</code> to the method signature
+     * is the simplest way to achieve this, but bear in mind the {@link #recycle()} method can be
+     * called concurrently.
+     * </p><p>
+     * See {@link SkiaImageRegionDecoder} and {@link SkiaPooledImageRegionDecoder} for examples of
+     * internal locking and synchronization.
+     * </p>
      * @param sRect Source image rectangle to decode.
      * @param sampleSize Sample size.
      * @return The decoded region. It is safe to return null if decoding fails.