trivial: javadoc improvements
diff --git a/src/main/java/org/apache/sling/api/uri/SlingUriBuilder.java b/src/main/java/org/apache/sling/api/uri/SlingUriBuilder.java
index 916b282..7a6c6e5 100644
--- a/src/main/java/org/apache/sling/api/uri/SlingUriBuilder.java
+++ b/src/main/java/org/apache/sling/api/uri/SlingUriBuilder.java
@@ -45,7 +45,7 @@
import org.slf4j.LoggerFactory;
/**
- * Builder for SlingUris that allows to set any properties of a {@link SlingUri}.
+ * Builder for immutable {@link SlingUri}s.
* <p>
* Example:
*
@@ -385,8 +385,11 @@
}
/**
- * Will rebase the uri based on the underlying resource structure. A resource resolver is necessary for this operation, hence
- * setResourceResolver() needs to be called before balanceResourcePath() or a create method that implicitly sets this has to be used.
+ * Will rebase the URI based on the underlying resource structure. Rebasing will potentially adjust the
+ * {@link #path}, {@link #selectors}, {@link extension} and {@code suffix} in a way that the path resolves to an existing resource.
+ * <p>
+ * A resource resolver is necessary for this operation, hence
+ * {@link #setResourceResolver(ResourceResolver)} needs to be called before {@link #rebaseResourcePath()} or a create method that implicitly sets this has to be used.
*
* @return the builder for method chaining
* @throws IllegalStateException
