SLING-5821 : Fix javadoc errors and warnings (WiP)
git-svn-id: https://svn.apache.org/repos/asf/sling/trunk@1751431 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/src/main/java/org/apache/sling/api/SlingHttpServletRequest.java b/src/main/java/org/apache/sling/api/SlingHttpServletRequest.java
index 228b34b..a5ac96c 100644
--- a/src/main/java/org/apache/sling/api/SlingHttpServletRequest.java
+++ b/src/main/java/org/apache/sling/api/SlingHttpServletRequest.java
@@ -37,6 +37,7 @@
import org.apache.sling.api.request.RequestProgressTracker;
import org.apache.sling.api.resource.Resource;
import org.apache.sling.api.resource.ResourceResolver;
+
import aQute.bnd.annotation.ProviderType;
/**
@@ -200,6 +201,11 @@
/**
* Same as {@link #getRequestDispatcher(Resource,RequestDispatcherOptions)}
* but using empty options.
+ * @param resource The {@link Resource} instance whose response content may
+ * be included by the returned dispatcher.
+ * @return a <code>RequestDispatcher</code> object that acts as a wrapper
+ * for the <code>resource</code> or <code>null</code> if an
+ * error occurs preparing the dispatcher.
*/
@CheckForNull RequestDispatcher getRequestDispatcher(@Nonnull Resource resource);
@@ -265,6 +271,7 @@
/**
* Returns the {@link RequestProgressTracker} of this request.
+ * @return The request progress tracker.
*/
@Nonnull RequestProgressTracker getRequestProgressTracker();
}
diff --git a/src/main/java/org/apache/sling/api/resource/ResourceResolver.java b/src/main/java/org/apache/sling/api/resource/ResourceResolver.java
index 19a665c..c8b3c60 100644
--- a/src/main/java/org/apache/sling/api/resource/ResourceResolver.java
+++ b/src/main/java/org/apache/sling/api/resource/ResourceResolver.java
@@ -55,7 +55,7 @@
* <code>resolve</code> methods and the <code>getResource</code> methods. The
* difference lies in the algorithm applied to find the requested resource and
* in the behavior in case a resource cannot be found:
- * <table>
+ * <table summary="">
* <tr>
* <th>Method Kind</th>
* <th>Access Algorithm</th>
@@ -360,6 +360,7 @@
* relative path, the search path entry and relative path may just be
* concatenated.
*
+ * @return The array of search paths
* @throws IllegalStateException if this resource resolver has already been
* {@link #close() closed}.
*/
@@ -643,7 +644,7 @@
/**
* Persist all pending changes.
*
- * @throws PersistenceException
+ * @throws PersistenceException If persisting the changes fails.
* @throws IllegalStateException if this resource resolver has already been
* {@link #close() closed}.
* @since 2.2 (Sling API Bundle 2.2.0)
@@ -652,6 +653,7 @@
/**
* Are there any pending changes?
+ * @return {@code true} if there are pending changes.
* @throws IllegalStateException if this resource resolver has already been
* {@link #close() closed}.
* @since 2.2 (Sling API Bundle 2.2.0)
diff --git a/src/main/java/org/apache/sling/api/resource/ResourceUtil.java b/src/main/java/org/apache/sling/api/resource/ResourceUtil.java
index 6e39780..0951e9b 100644
--- a/src/main/java/org/apache/sling/api/resource/ResourceUtil.java
+++ b/src/main/java/org/apache/sling/api/resource/ResourceUtil.java
@@ -41,8 +41,11 @@
/**
* Resolves relative path segments '.' and '..' in the absolute path.
- * Returns null if not possible (.. points above root) or if path is not
+ * Returns {@code null} if not possible (.. points above root) or if path is not
* absolute.
+ *
+ * @param path The path to normalize
+ * @return The normalized path or {@code null}.
*/
public static @CheckForNull String normalize(@Nonnull String path) {
@@ -185,7 +188,7 @@
* @return <code>null</code> if <code>path</code> doesn't have an ancestor at the
* specified <code>level</code>.
* @throws IllegalArgumentException If the path cannot be normalized by the
- * {@link #normalize(String)} method or if <code>level</code> < 0.
+ * {@link #normalize(String)} method or if <code>level</code> < 0.
* @throws NullPointerException If <code>path</code> is <code>null</code>.
* @since 2.2 (Sling API Bundle 2.2.0)
*/
@@ -206,12 +209,13 @@
/**
* Utility method returns the parent resource of the resource.
*
+ * @param rsrc The resource to get the parent of.
+ * @return The parent resource or null if the rsrc is the root.
* @throws NullPointerException If <code>rsrc</code> is <code>null</code>.
* @throws org.apache.sling.api.SlingException If an error occurs trying to
* get the resource object from the path.
* @throws IllegalStateException if the resource resolver has already been
* closed}.
- * @return The parent resource or null if the rsrc is the root.
* @deprecated since 2.1.0, use {@link Resource#getParent()} instead
*/
@Deprecated
@@ -222,6 +226,8 @@
/**
* Utility method returns the name of the resource.
*
+ * @param rsrc The resource to get the name from.
+ * @return The name of the resource
* @throws NullPointerException If <code>rsrc</code> is <code>null</code>.
* @deprecated since 2.1.0, use {@link Resource#getName()} instead
*/
@@ -478,6 +484,7 @@
*
* @param iterator A resource iterator.
* @param <T> The adapted type
+ * @return An iterator of the adapted objects
* @since 2.0.6 (Sling API Bundle 2.0.6)
*/
public static @Nonnull <T> Iterator<T> adaptTo(final @Nonnull Iterator<Resource> iterator,
@@ -530,6 +537,7 @@
* get/create the resource object from the path.
* @throws IllegalStateException if the resource resolver has already been
* closed}.
+ * @throws PersistenceException If a persistence error occurs.
* @since 2.3.0 (Sling API Bundle 2.4.0)
*/
public static @Nonnull Resource getOrCreateResource(
@@ -564,6 +572,7 @@
* get/create the resource object from the path.
* @throws IllegalStateException if the resource resolver has already been
* closed}.
+ * @throws PersistenceException If a persistence error occurs.
* @since 2.3.0 (Sling API Bundle 2.4.0)
*/
public static @Nonnull Resource getOrCreateResource(
@@ -608,6 +617,7 @@
* get/create the resource object from the path.
* @throws IllegalStateException if the resource resolver has already been
* closed}.
+ * @throws PersistenceException If a persistence error occurs.
*/
private static Resource getOrCreateResourceInternal(
final ResourceResolver resolver,
diff --git a/src/main/java/org/apache/sling/api/resource/ResourceWrapper.java b/src/main/java/org/apache/sling/api/resource/ResourceWrapper.java
index 0446323..1869a9d 100644
--- a/src/main/java/org/apache/sling/api/resource/ResourceWrapper.java
+++ b/src/main/java/org/apache/sling/api/resource/ResourceWrapper.java
@@ -36,6 +36,7 @@
/**
* Creates a new wrapper instance delegating all method calls to the given
* <code>resource</code>.
+ * @param resource The resource to wrap
*/
public ResourceWrapper(@Nonnull final Resource resource) {
this.resource = resource;
@@ -45,6 +46,7 @@
* Returns the <code>Resource</code> wrapped by this instance. This method
* can be overwritten by subclasses if required. All methods implemented by
* this class use this method to get the resource object.
+ * @return The resource wrapped by this instance.
*/
public Resource getResource() {
return resource;
@@ -54,6 +56,7 @@
* Returns the value of calling <code>getPath</code> on the
* {@link #getResource() wrapped resource}.
*/
+ @Override
public String getPath() {
return getResource().getPath();
}
@@ -64,6 +67,7 @@
*
* @since 2.1.0 (Sling API Bundle 2.1.0)
*/
+ @Override
public String getName() {
return getResource().getName();
}
@@ -74,6 +78,7 @@
*
* @since 2.1.0 (Sling API Bundle 2.1.0)
*/
+ @Override
public Resource getParent() {
return getResource().getParent();
}
@@ -84,6 +89,7 @@
*
* @since 2.1.0 (Sling API Bundle 2.1.0)
*/
+ @Override
public Resource getChild(String relPath) {
return getResource().getChild(relPath);
}
@@ -94,6 +100,7 @@
*
* @since 2.1.0 (Sling API Bundle 2.1.0)
*/
+ @Override
public Iterator<Resource> listChildren() {
return getResource().listChildren();
}
@@ -101,6 +108,7 @@
/**
* @see org.apache.sling.api.resource.Resource#getChildren()
*/
+ @Override
public Iterable<Resource> getChildren() {
return getResource().getChildren();
}
@@ -109,6 +117,7 @@
* Returns the value of calling <code>getResourceMetadata</code> on the
* {@link #getResource() wrapped resource}.
*/
+ @Override
public ResourceMetadata getResourceMetadata() {
return getResource().getResourceMetadata();
}
@@ -117,6 +126,7 @@
* Returns the value of calling <code>getResourceResolver</code> on the
* {@link #getResource() wrapped resource}.
*/
+ @Override
public ResourceResolver getResourceResolver() {
return getResource().getResourceResolver();
}
@@ -125,6 +135,7 @@
* Returns the value of calling <code>getResourceType</code> on the
* {@link #getResource() wrapped resource}.
*/
+ @Override
public String getResourceType() {
return getResource().getResourceType();
}
@@ -133,6 +144,7 @@
* Returns the value of calling <code>getResourceSuperType</code> on the
* {@link #getResource() wrapped resource}.
*/
+ @Override
public String getResourceSuperType() {
return getResource().getResourceSuperType();
}
@@ -143,7 +155,8 @@
*
* @since 2.4.4 (Sling API Bundle 2.5.0)
*/
- public boolean hasChildren() {
+ @Override
+ public boolean hasChildren() {
return getResource().hasChildren();
}
@@ -153,6 +166,7 @@
*
* @since 2.1.0 (Sling API Bundle 2.1.0)
*/
+ @Override
public boolean isResourceType(final String resourceType) {
return getResource().isResourceType(resourceType);
}
@@ -161,6 +175,7 @@
* Returns the value of calling <code>adaptTo</code> on the
* {@link #getResource() wrapped resource}.
*/
+ @Override
public <AdapterType> AdapterType adaptTo(Class<AdapterType> type) {
return getResource().adaptTo(type);
}
@@ -168,6 +183,7 @@
/**
* @see org.apache.sling.api.resource.Resource#getValueMap()
*/
+ @Override
public ValueMap getValueMap() {
return getResource().getValueMap();
}
diff --git a/src/main/java/org/apache/sling/api/resource/SyntheticResource.java b/src/main/java/org/apache/sling/api/resource/SyntheticResource.java
index 8f5efd9..fc9b59b 100644
--- a/src/main/java/org/apache/sling/api/resource/SyntheticResource.java
+++ b/src/main/java/org/apache/sling/api/resource/SyntheticResource.java
@@ -42,6 +42,9 @@
/**
* Creates a synthetic resource with the given <code>path</code> and
* <code>resourceType</code>.
+ * @param resourceResolver The resource resolver
+ * @param path The resource path
+ * @param resourceType The type of the resource
*/
public SyntheticResource(ResourceResolver resourceResolver, String path,
String resourceType) {
@@ -55,6 +58,9 @@
/**
* Creates a synthetic resource with the given <code>ResourceMetadata</code>
* and <code>resourceType</code>.
+ * @param resourceResolver The resource resolver
+ * @param rm The resource meta data
+ * @param resourceType The type of the resource
*/
public SyntheticResource(ResourceResolver resourceResolver, ResourceMetadata rm,
String resourceType) {
@@ -67,6 +73,7 @@
/**
* @see org.apache.sling.api.resource.Resource#getPath()
*/
+ @Override
public @Nonnull String getPath() {
return path;
}
@@ -74,6 +81,7 @@
/**
* @see org.apache.sling.api.resource.Resource#getResourceType()
*/
+ @Override
public @Nonnull String getResourceType() {
return resourceType;
}
@@ -81,6 +89,7 @@
/**
* Synthetic resources by default do not have a resource super type.
*/
+ @Override
public String getResourceSuperType() {
return null;
}
@@ -89,6 +98,7 @@
* Returns a resource metadata object containing just the path of this
* resource as the {@link ResourceMetadata#RESOLUTION_PATH} property.
*/
+ @Override
public @Nonnull ResourceMetadata getResourceMetadata() {
return resourceMetadata;
}
@@ -97,6 +107,7 @@
* Returns the {@link ResourceResolver} with which this synthetic resource
* is related or <code>null</code> if none.
*/
+ @Override
public @Nonnull ResourceResolver getResourceResolver() {
return resourceResolver;
}
diff --git a/src/main/java/org/apache/sling/api/resource/path/PathSet.java b/src/main/java/org/apache/sling/api/resource/path/PathSet.java
index a2189db..2feeaa5 100644
--- a/src/main/java/org/apache/sling/api/resource/path/PathSet.java
+++ b/src/main/java/org/apache/sling/api/resource/path/PathSet.java
@@ -78,7 +78,7 @@
/**
* Create a path set from a collection of strings
- * @param paths The collection of strings
+ * @param strings The array of strings
* @return The path set
*/
public static PathSet fromStrings(final String...strings) {
@@ -127,7 +127,7 @@
* of the paths in this set.
* @param otherPath
* @return The path which matches the provided path, {@code null} otherwise.
- * @see {@link Path#matches(String)}
+ * @see Path#matches(String)
*/
public Path matches(final String otherPath) {
for(final Path p : this.paths) {
diff --git a/src/main/java/org/apache/sling/api/servlets/HtmlResponse.java b/src/main/java/org/apache/sling/api/servlets/HtmlResponse.java
index 798628b..138c2ec 100644
--- a/src/main/java/org/apache/sling/api/servlets/HtmlResponse.java
+++ b/src/main/java/org/apache/sling/api/servlets/HtmlResponse.java
@@ -293,7 +293,9 @@
}
/**
- * Records a 'moved' change. <p/> Note: the moved change only records the
+ * Records a 'moved' change.
+ * <p>
+ * Note: the moved change only records the
* basic move command. the implied changes on the moved properties and sub
* nodes are not recorded.
*
@@ -305,7 +307,9 @@
}
/**
- * Records a 'copied' change. <p/> Note: the copy change only records the
+ * Records a 'copied' change.
+ * <p>
+ * Note: the copy change only records the
* basic copy command. the implied changes on the copied properties and sub
* nodes are not recorded.
*
