Author: cziegeler Date: Tue Jul 5 10:04:27 2016 New Revision: 1751431 URL: http://svn.apache.org/viewvc?rev=1751431&view=rev Log: SLING-5821 : Fix javadoc errors and warnings (WiP)
Modified: sling/trunk/bundles/api/src/main/java/org/apache/sling/api/SlingHttpServletRequest.java sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/ResourceResolver.java sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/ResourceUtil.java sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/ResourceWrapper.java sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/SyntheticResource.java sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/path/PathSet.java sling/trunk/bundles/api/src/main/java/org/apache/sling/api/servlets/HtmlResponse.java Modified: sling/trunk/bundles/api/src/main/java/org/apache/sling/api/SlingHttpServletRequest.java URL: http://svn.apache.org/viewvc/sling/trunk/bundles/api/src/main/java/org/apache/sling/api/SlingHttpServletRequest.java?rev=1751431&r1=1751430&r2=1751431&view=diff ============================================================================== --- sling/trunk/bundles/api/src/main/java/org/apache/sling/api/SlingHttpServletRequest.java (original) +++ sling/trunk/bundles/api/src/main/java/org/apache/sling/api/SlingHttpServletRequest.java Tue Jul 5 10:04:27 2016 @@ -37,6 +37,7 @@ import org.apache.sling.api.request.Requ 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 @@ public interface SlingHttpServletRequest /** * 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 @@ public interface SlingHttpServletRequest /** * Returns the {@link RequestProgressTracker} of this request. + * @return The request progress tracker. */ @Nonnull RequestProgressTracker getRequestProgressTracker(); } Modified: sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/ResourceResolver.java URL: http://svn.apache.org/viewvc/sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/ResourceResolver.java?rev=1751431&r1=1751430&r2=1751431&view=diff ============================================================================== --- sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/ResourceResolver.java (original) +++ sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/ResourceResolver.java Tue Jul 5 10:04:27 2016 @@ -55,7 +55,7 @@ import aQute.bnd.annotation.ProviderType * <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 @@ public interface ResourceResolver extend * 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 @@ public interface ResourceResolver extend /** * 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 @@ public interface ResourceResolver extend /** * 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) Modified: sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/ResourceUtil.java URL: http://svn.apache.org/viewvc/sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/ResourceUtil.java?rev=1751431&r1=1751430&r2=1751431&view=diff ============================================================================== --- sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/ResourceUtil.java (original) +++ sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/ResourceUtil.java Tue Jul 5 10:04:27 2016 @@ -41,8 +41,11 @@ public class ResourceUtil { /** * 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 @@ public class ResourceUtil { * @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 @@ public class ResourceUtil { /** * 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 @@ public class ResourceUtil { /** * 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 @@ public class ResourceUtil { * * @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 @@ public class ResourceUtil { * 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 @@ public class ResourceUtil { * 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 @@ public class ResourceUtil { * 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, Modified: sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/ResourceWrapper.java URL: http://svn.apache.org/viewvc/sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/ResourceWrapper.java?rev=1751431&r1=1751430&r2=1751431&view=diff ============================================================================== --- sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/ResourceWrapper.java (original) +++ sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/ResourceWrapper.java Tue Jul 5 10:04:27 2016 @@ -36,6 +36,7 @@ public class ResourceWrapper implements /** * 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 @@ public class ResourceWrapper implements * 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 @@ public class ResourceWrapper implements * 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 @@ public class ResourceWrapper implements * * @since 2.1.0 (Sling API Bundle 2.1.0) */ + @Override public String getName() { return getResource().getName(); } @@ -74,6 +78,7 @@ public class ResourceWrapper implements * * @since 2.1.0 (Sling API Bundle 2.1.0) */ + @Override public Resource getParent() { return getResource().getParent(); } @@ -84,6 +89,7 @@ public class ResourceWrapper implements * * @since 2.1.0 (Sling API Bundle 2.1.0) */ + @Override public Resource getChild(String relPath) { return getResource().getChild(relPath); } @@ -94,6 +100,7 @@ public class ResourceWrapper implements * * @since 2.1.0 (Sling API Bundle 2.1.0) */ + @Override public Iterator<Resource> listChildren() { return getResource().listChildren(); } @@ -101,6 +108,7 @@ public class ResourceWrapper implements /** * @see org.apache.sling.api.resource.Resource#getChildren() */ + @Override public Iterable<Resource> getChildren() { return getResource().getChildren(); } @@ -109,6 +117,7 @@ public class ResourceWrapper implements * 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 @@ public class ResourceWrapper implements * 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 @@ public class ResourceWrapper implements * 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 @@ public class ResourceWrapper implements * 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 @@ public class ResourceWrapper implements * * @since 2.4.4 (Sling API Bundle 2.5.0) */ - public boolean hasChildren() { + @Override + public boolean hasChildren() { return getResource().hasChildren(); } @@ -153,6 +166,7 @@ public class ResourceWrapper implements * * @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 @@ public class ResourceWrapper implements * 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 @@ public class ResourceWrapper implements /** * @see org.apache.sling.api.resource.Resource#getValueMap() */ + @Override public ValueMap getValueMap() { return getResource().getValueMap(); } Modified: sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/SyntheticResource.java URL: http://svn.apache.org/viewvc/sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/SyntheticResource.java?rev=1751431&r1=1751430&r2=1751431&view=diff ============================================================================== --- sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/SyntheticResource.java (original) +++ sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/SyntheticResource.java Tue Jul 5 10:04:27 2016 @@ -42,6 +42,9 @@ public class SyntheticResource extends A /** * 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 @@ public class SyntheticResource extends A /** * 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 @@ public class SyntheticResource extends A /** * @see org.apache.sling.api.resource.Resource#getPath() */ + @Override public @Nonnull String getPath() { return path; } @@ -74,6 +81,7 @@ public class SyntheticResource extends A /** * @see org.apache.sling.api.resource.Resource#getResourceType() */ + @Override public @Nonnull String getResourceType() { return resourceType; } @@ -81,6 +89,7 @@ public class SyntheticResource extends A /** * Synthetic resources by default do not have a resource super type. */ + @Override public String getResourceSuperType() { return null; } @@ -89,6 +98,7 @@ public class SyntheticResource extends A * 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 @@ public class SyntheticResource extends A * Returns the {@link ResourceResolver} with which this synthetic resource * is related or <code>null</code> if none. */ + @Override public @Nonnull ResourceResolver getResourceResolver() { return resourceResolver; } Modified: sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/path/PathSet.java URL: http://svn.apache.org/viewvc/sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/path/PathSet.java?rev=1751431&r1=1751430&r2=1751431&view=diff ============================================================================== --- sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/path/PathSet.java (original) +++ sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/path/PathSet.java Tue Jul 5 10:04:27 2016 @@ -78,7 +78,7 @@ public class PathSet implements Iterable /** * 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 @@ public class PathSet implements Iterable * 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) { Modified: sling/trunk/bundles/api/src/main/java/org/apache/sling/api/servlets/HtmlResponse.java URL: http://svn.apache.org/viewvc/sling/trunk/bundles/api/src/main/java/org/apache/sling/api/servlets/HtmlResponse.java?rev=1751431&r1=1751430&r2=1751431&view=diff ============================================================================== --- sling/trunk/bundles/api/src/main/java/org/apache/sling/api/servlets/HtmlResponse.java (original) +++ sling/trunk/bundles/api/src/main/java/org/apache/sling/api/servlets/HtmlResponse.java Tue Jul 5 10:04:27 2016 @@ -293,7 +293,9 @@ public class HtmlResponse { } /** - * 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 @@ public class HtmlResponse { } /** - * 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. *