diff --git a/src/main/java/org/apache/sling/resourceresolver/impl/mapping/MapEntries.java b/src/main/java/org/apache/sling/resourceresolver/impl/mapping/MapEntries.java
index f7052e3..ee6cf34 100644
--- a/src/main/java/org/apache/sling/resourceresolver/impl/mapping/MapEntries.java
+++ b/src/main/java/org/apache/sling/resourceresolver/impl/mapping/MapEntries.java
@@ -589,9 +589,6 @@
         this.eventAdmin = null;
     }
 
-    /**
-     * This is for the web console plugin
-     */
     @Override
     public List<MapEntry> getResolveMaps() {
         final List<MapEntry> entries = new ArrayList<>();
@@ -602,10 +599,6 @@
         return Collections.unmodifiableList(entries);
     }
 
-    /**
-     * Calculate the resolve maps. As the entries have to be sorted by pattern
-     * length, we have to create a new list containing all relevant entries.
-     */
     @Override
     public Iterator<MapEntry> getResolveMapsIterator(final String requestPath) {
         String key = null;
diff --git a/src/main/java/org/apache/sling/resourceresolver/impl/mapping/MapEntriesHandler.java b/src/main/java/org/apache/sling/resourceresolver/impl/mapping/MapEntriesHandler.java
index b162eb5..0087075 100644
--- a/src/main/java/org/apache/sling/resourceresolver/impl/mapping/MapEntriesHandler.java
+++ b/src/main/java/org/apache/sling/resourceresolver/impl/mapping/MapEntriesHandler.java
@@ -24,9 +24,20 @@
 import java.util.List;
 import java.util.Map;
 
+import org.apache.sling.api.resource.ResourceResolver;
+import org.apache.sling.api.resource.mapping.ResourceMapper;
+import org.jetbrains.annotations.NotNull;
+
 /**
- * Interface for MapEntries to only expose the public methods
- * used during resource resolving
+ * Exposes low-level methods used for resource resolving and mapping
+ * 
+ * <p>This interface is intended for bundle internal use and its main goal is to
+ * prevent accidental modifications of the internal state by only exposing 
+ * accessor methods.</p>
+ * 
+ * @see ResourceMapper
+ * @see ResourceResolver#map(String)
+ * @see ResourceResolver#map(javax.servlet.http.HttpServletRequest, String)
  */
 public interface MapEntriesHandler {
 
@@ -58,27 +69,55 @@
         }
     };
 
-    Map<String, String> getAliasMap(String parentPath);
-
     /**
-     * Calculate the resolve maps. As the entries have to be sorted by pattern
-     * length, we have to create a new list containing all relevant entries.
-     */
-    Iterator<MapEntry> getResolveMapsIterator(String requestPath);
-
-    Collection<MapEntry> getMapMaps();
-
-    /**
-     * This is for the web console plugin
-     */
-    List<MapEntry> getResolveMaps();
-    
-    /*
-     * Returns vanity path information
+     * Returns all alias entries that for children of the specified <tt>parentPath</tt>
      * 
-     * <p>Maps resources paths to a list of vanity paths.</p>
+     * <p>The returned map has resource names as keys and aliases as values.</p>
+     * 
+     * @param parentPath the parent path
+     * @return a map of all child alias entries, possibly empty
+     */
+    @NotNull Map<String, String> getAliasMap(@NotNull String parentPath);
+
+    /**
+     * Creates an iterator over the possibly applicable mapping entries for resolving a resource
+     * 
+     * <p>This method uses the request path to filter out any unapplicable mapping entries and
+     * is therefore preferrable over {@link #getResolveMaps()}.</p>
+     * 
+     * <p>The iterator will iterate over the mapping entries in the order of the pattern length.</p> 
+     * 
+     * @return the map entry iterator
+     */
+    @NotNull Iterator<MapEntry> getResolveMapsIterator(@NotNull String requestPath);
+
+    /**
+     * Return a flat listing of map entries used for mapping resources to URLs
+     * 
+     * <p>This method returns information about all mapping rules. Note that vanity paths are excluded.</p>
+     * 
+     * @return an unmodifiable collection of map entries
+     */
+    @NotNull Collection<MapEntry> getMapMaps();
+
+    /**
+     * Creates a flat listing of all the map entries used for resolving URLs to resources
+     * 
+     * <p>This method returns information about all resolve rules, such as vanity paths, mapping entries,
+     * virtual URLs and URL mappings.</p>
+     * 
+     * <p>This list is computed on-demand and therefore should not be used in performance-critical code.</p>
+     * 
+     * @return an unmodifiable, sorted, list of resolution map entries
+     */
+    @NotNull List<MapEntry> getResolveMaps();
+    
+    /**
+     * Returns vanity paths mappings
+     * 
+     * <p>The keys in the map are resource paths and the values are the vanity mappings.</p>
      * 
      * @return an unmodifiable list of vanity path mappings
      */
-    Map<String, List<String>> getVanityPathMappings();
+    @NotNull Map<String, List<String>> getVanityPathMappings();
 }
diff --git a/src/main/java/org/apache/sling/resourceresolver/impl/mapping/MapEntry.java b/src/main/java/org/apache/sling/resourceresolver/impl/mapping/MapEntry.java
index 2fc2b56..af139bb 100644
--- a/src/main/java/org/apache/sling/resourceresolver/impl/mapping/MapEntry.java
+++ b/src/main/java/org/apache/sling/resourceresolver/impl/mapping/MapEntry.java
@@ -33,9 +33,8 @@
 /**
  * The <code>MapEntry</code> class represents a mapping entry in the mapping
  * configuration tree at <code>/etc/map</code>.
- * <p>
  *
- * @see "http://cwiki.apache.org/SLING/flexible-resource-resolution.html"
+ * @see <a href="https://sling.apache.org/documentation/the-sling-engine/mappings-for-resource-resolution.html">Mappings for Resource Resolution</a>
  */
 public class MapEntry implements Comparable<MapEntry> {
 
@@ -268,7 +267,12 @@
         this.order = order;
     }
 
-    // Returns the replacement or null if the value does not match
+    /**
+     * Replaces the specified value according to the rules of this entry
+     * 
+     * @param value the value to replace
+     * @return a replaced value of <code>null</code> if the value does not match
+     */
     public String[] replace(final String value) {
         final Matcher m = urlPattern.matcher(value);
         if (m.find()) {