diff --git a/components/common/src/ome/api/RawPixelsStore.java b/components/common/src/ome/api/RawPixelsStore.java
index 63c816d0912..4adf2053771 100644
--- a/components/common/src/ome/api/RawPixelsStore.java
+++ b/components/common/src/ome/api/RawPixelsStore.java
@@ -130,10 +130,34 @@ public interface RawPixelsStore extends StatefulServiceInterface {
 
     public Object getResolutionDescriptions();
 
+    /**
+     * Retrieves the number of resolution levels that the backing
+     * pixels pyramid contains.
+     * @return The number of resolution levels. This value does not
+     * necessarily indicate either the presence or absence of a
+     * pixels pyramid.
+     **/
     public int getResolutionLevels();
 
+    /**
+     * Retrieves the active resolution level.
+     * @return The active resolution level.  The level will be non-negative and less
+     * than {@link #getResolutionLevels()}.  Resolution level 0 is the smallest
+     * resolution and resolution level <code>getResolutionLevels() - 1</code>
+     * is the largest resolution.  This is the inverse of how Bio-Formats indexes
+     * resolutions.
+     */
     public int getResolutionLevel();
 
+    /**
+     * Sets the active resolution level.
+     * @param resolutionLevel The resolution level to be used.
+     * The level should be non-negative and less than
+     * {@link #getResolutionLevels()}.  * Resolution level 0 is the smallest
+     * resolution and resolution level <code>getResolutionLevels() - 1</code>
+     * is the largest resolution.  This is the inverse of how Bio-Formats indexes
+     * resolutions.
+     */
     public void setResolutionLevel(int resolutionLevel);
 
     public int[] getTileSize();
diff --git a/components/common/src/omeis/providers/re/RenderingEngine.java b/components/common/src/omeis/providers/re/RenderingEngine.java
index 0ab09edf88f..e30fc6145a7 100644
--- a/components/common/src/omeis/providers/re/RenderingEngine.java
+++ b/components/common/src/omeis/providers/re/RenderingEngine.java
@@ -602,10 +602,13 @@ public void setQuantizationMap(int w, Family family, double coefficient,
 
     public Object getResolutionDescriptions();
 
+    /* @see ome.io.nio.PixelBuffer#getResolutionLevels() */
     public int getResolutionLevels();
 
+    /* @see ome.io.nio.PixelBuffer#getResolutionLevel() */
     public int getResolutionLevel();
 
+    /* @see ome.io.nio.PixelBuffer#setResolutionLevel(int) */
     public void setResolutionLevel(int resolutionLevel);
 
     public int[] getTileSize();
diff --git a/components/rendering/src/omeis/providers/re/Renderer.java b/components/rendering/src/omeis/providers/re/Renderer.java
index 3a0415c2590..fe564e18d4f 100644
--- a/components/rendering/src/omeis/providers/re/Renderer.java
+++ b/components/rendering/src/omeis/providers/re/Renderer.java
@@ -953,6 +953,7 @@ public double getPixelsTypeUpperBound(int w)
     /**
      * Sets the active resolution level.
      * @param resolutionLevel The resolution level to be used by the renderer.
+     * @see ome.io.nio.PixelBuffer#setResolutionLevel(int)
      **/
     public void setResolutionLevel(int resolutionLevel)
     {
@@ -962,6 +963,7 @@ public void setResolutionLevel(int resolutionLevel)
     /**
      * Retrieves the active resolution level.
      * @return The active resolution level.
+     * @see ome.io.nio.PixelBuffer#getResolutionLevel()
      **/
     public int getResolutionLevel()
     {
@@ -974,6 +976,7 @@ public int getResolutionLevel()
      * @return The number of resolution levels. This value does not
      * necessarily indicate either the presence or absence of a
      * pixels pyramid.
+     * @see ome.io.nio.PixelBuffer#getResolutionLevels()
      **/
     public int getResolutionLevels()
     {
diff --git a/components/romio/src/ome/io/nio/PixelBuffer.java b/components/romio/src/ome/io/nio/PixelBuffer.java
index 07b7de7db56..a7dd2eec1b4 100644
--- a/components/romio/src/ome/io/nio/PixelBuffer.java
+++ b/components/romio/src/ome/io/nio/PixelBuffer.java
@@ -678,14 +678,22 @@ public void setTimepoint(byte[] buffer, Integer t) throws IOException,
 
     /**
      * Retrieves the active resolution level.
-     * @return The active resolution level.
+     * @return The active resolution level.  The level will be non-negative and less
+     * than {@link #getResolutionLevels()}.  Resolution level 0 is the smallest
+     * resolution and resolution level <code>getResolutionLevels() - 1</code>
+     * is the largest resolution.  This is the inverse of how Bio-Formats indexes
+     * resolutions.
      **/
     public int getResolutionLevel();
 
     /**
      * Sets the active resolution level.
      * @param resolutionLevel The resolution level to be used by
-     * the pixel buffer.
+     * the pixel buffer.  The level should be non-negative and less
+     * than {@link #getResolutionLevels()}.  Resolution level 0 is the smallest
+     * resolution and resolution level <code>getResolutionLevels() - 1</code>
+     * is the largest resolution.  This is the inverse of how Bio-Formats indexes
+     * resolutions.
      **/
     public void setResolutionLevel(int resolutionLevel);