You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sling.apache.org by jo...@apache.org on 2021/06/04 09:12:01 UTC

[sling-org-apache-sling-servlets-post] branch bugfix/SLING-10442-fix-javadoc created (now 40da86f)

This is an automated email from the ASF dual-hosted git repository.

joerghoh pushed a change to branch bugfix/SLING-10442-fix-javadoc
in repository https://gitbox.apache.org/repos/asf/sling-org-apache-sling-servlets-post.git.


      at 40da86f  fix javadoc warnings and errors

This branch includes the following new commits:

     new 40da86f  fix javadoc warnings and errors

The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.


[sling-org-apache-sling-servlets-post] 01/01: fix javadoc warnings and errors

Posted by jo...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

joerghoh pushed a commit to branch bugfix/SLING-10442-fix-javadoc
in repository https://gitbox.apache.org/repos/asf/sling-org-apache-sling-servlets-post.git

commit 40da86fc8c17068ccaacce96db533bc89fa5813a
Author: Joerg Hoh <jh...@adobe.com>
AuthorDate: Fri Jun 4 11:11:43 2021 +0200

    fix javadoc warnings and errors
---
 .../sling/servlets/post/AbstractPostOperation.java | 23 ++++++++-------
 .../sling/servlets/post/AbstractPostResponse.java  | 34 ++++++++++++----------
 .../servlets/post/AbstractSlingPostOperation.java  |  8 ++---
 .../apache/sling/servlets/post/Modification.java   |  6 ++++
 .../apache/sling/servlets/post/PostOperation.java  | 12 +++++---
 .../apache/sling/servlets/post/PostResponse.java   | 15 +++++++++-
 .../sling/servlets/post/SlingPostOperation.java    |  2 +-
 .../sling/servlets/post/impl/helper/Chunk.java     |  6 ++++
 .../servlets/post/impl/helper/DateParser.java      |  2 --
 .../servlets/post/impl/helper/JCRSupport.java      |  9 +++++-
 .../servlets/post/impl/helper/JCRSupportImpl.java  | 27 ++++++++---------
 .../servlets/post/impl/helper/ReferenceParser.java |  9 +++---
 .../servlets/post/impl/helper/RequestProperty.java | 18 ++++++++----
 .../post/impl/helper/SlingFileUploadHandler.java   | 22 ++++++++------
 .../impl/helper/SlingPropertyValueHandler.java     |  7 +++--
 .../servlets/post/impl/helper/StreamedChunk.java   |  2 +-
 .../impl/operations/AbstractCopyMoveOperation.java |  6 ++--
 .../impl/operations/AbstractCreateOperation.java   | 12 ++++++++
 .../post/impl/operations/DeleteOperation.java      |  2 ++
 19 files changed, 144 insertions(+), 78 deletions(-)

diff --git a/src/main/java/org/apache/sling/servlets/post/AbstractPostOperation.java b/src/main/java/org/apache/sling/servlets/post/AbstractPostOperation.java
index ded1d04..e62e275 100644
--- a/src/main/java/org/apache/sling/servlets/post/AbstractPostOperation.java
+++ b/src/main/java/org/apache/sling/servlets/post/AbstractPostOperation.java
@@ -214,8 +214,9 @@ public abstract class AbstractPostOperation implements PostOperation {
      *            representing the operations done.
      * @throws RepositoryException Maybe thrown if any error occurrs while
      *             accessing the repository.
-     * @throws TemporaryPersistenceException 
-     * @throws PreconditionViolatedPersistenceException 
+     * @throws TemporaryPersistenceException if a retry could help
+     * @throws PreconditionViolatedPersistenceException if a retry doesn't make sense
+     *             and some preconditions should be changed.
      */
     protected abstract void doRun(SlingHttpServletRequest request,
             PostResponse response,
@@ -255,7 +256,7 @@ public abstract class AbstractPostOperation implements PostOperation {
      * @param session The JCR session
      * @param request The http request
      * @return {@code true} if a save is required.
-     * @throws RepositoryException
+     * @throws RepositoryException a repository exception
      */
     protected boolean isSessionSaveRequired(Session session, SlingHttpServletRequest request)
             throws RepositoryException {
@@ -268,7 +269,7 @@ public abstract class AbstractPostOperation implements PostOperation {
      * @param path The path
      * @param session The JCR session
      * @return The path without the workspace
-     * @throws RepositoryException
+     * @throws RepositoryException a repository exception
      */
     protected String removeAndValidateWorkspace(String path, Session session) throws RepositoryException {
         final int wsSepPos = path.indexOf(":/");
@@ -363,11 +364,11 @@ public abstract class AbstractPostOperation implements PostOperation {
 
     /**
      * Returns true if any of the request parameters starts with
-     * {@link SlingPostConstants#ITEM_PREFIX_RELATIVE_CURRENT <code>./</code>}.
+     * {@link SlingPostConstants#ITEM_PREFIX_RELATIVE_CURRENT ./}.
      * In this case only parameters starting with either of the prefixes
-     * {@link SlingPostConstants#ITEM_PREFIX_RELATIVE_CURRENT <code>./</code>},
-     * {@link SlingPostConstants#ITEM_PREFIX_RELATIVE_PARENT <code>../</code>}
-     * and {@link SlingPostConstants#ITEM_PREFIX_ABSOLUTE <code>/</code>} are
+     * {@link SlingPostConstants#ITEM_PREFIX_RELATIVE_CURRENT ./},
+     * {@link SlingPostConstants#ITEM_PREFIX_RELATIVE_PARENT ../}
+     * and {@link SlingPostConstants#ITEM_PREFIX_ABSOLUTE /} are
      * considered as providing content to be stored. Otherwise all parameters
      * not starting with the command prefix <code>:</code> are considered as
      * parameters to be stored.
@@ -392,9 +393,9 @@ public abstract class AbstractPostOperation implements PostOperation {
     /**
      * Returns <code>true</code> if the <code>name</code> starts with either
      * of the prefixes
-     * {@link SlingPostConstants#ITEM_PREFIX_RELATIVE_CURRENT <code>./</code>},
-     * {@link SlingPostConstants#ITEM_PREFIX_RELATIVE_PARENT <code>../</code>}
-     * and {@link SlingPostConstants#ITEM_PREFIX_ABSOLUTE <code>/</code>}.
+     * {@link SlingPostConstants#ITEM_PREFIX_RELATIVE_CURRENT ./},
+     * {@link SlingPostConstants#ITEM_PREFIX_RELATIVE_PARENT ../}
+     * and {@link SlingPostConstants#ITEM_PREFIX_ABSOLUTE /}.
      *
      * @param name The name
      * @return {@code true} if the name has a prefix
diff --git a/src/main/java/org/apache/sling/servlets/post/AbstractPostResponse.java b/src/main/java/org/apache/sling/servlets/post/AbstractPostResponse.java
index 57e6336..f6b0dfa 100644
--- a/src/main/java/org/apache/sling/servlets/post/AbstractPostResponse.java
+++ b/src/main/java/org/apache/sling/servlets/post/AbstractPostResponse.java
@@ -82,41 +82,35 @@ public abstract class AbstractPostResponse implements PostResponse {
     // ---------- Settings for the response ------------------------------------
 
     /**
-     * Returns the referer as from the 'referer' request header.
+     * {@inheritDoc}
      */
     public String getReferer() {
         return getProperty(PN_REFERER, String.class);
     }
 
     /**
-     * Sets the referer property
+     * {@inheritDoc}
      */
     public void setReferer(String referer) {
         setProperty(PN_REFERER, referer);
     }
 
     /**
-     * Returns the absolute path of the item upon which the request operated.
-     * <p>
-     * If the {@link #setPath(String)} method has not been called yet, this
-     * method returns <code>null</code>.
+     * {@inheritDoc}
      */
     public String getPath() {
         return getProperty(PN_PATH, String.class);
     }
 
     /**
-     * Sets the absolute path of the item upon which the request operated.
+     * {@inheritDoc}
      */
     public void setPath(String path) {
         setProperty(PN_PATH, path);
     }
 
     /**
-     * Returns <code>true</code> if this was a create request.
-     * <p>
-     * Before calling the {@link #setCreateRequest(boolean)} method, this method
-     * always returns <code>false</code>.
+     * {@inheritDoc}
      */
     public boolean isCreateRequest() {
         final Boolean isCreateRequest = getProperty(PN_IS_CREATED,
@@ -127,17 +121,14 @@ public abstract class AbstractPostResponse implements PostResponse {
     }
 
     /**
-     * Sets whether the request was a create request or not.
+     * {@inheritDoc}
      */
     public void setCreateRequest(boolean isCreateRequest) {
         setProperty(PN_IS_CREATED, isCreateRequest);
     }
 
     /**
-     * Returns the location of the modification. this is the externalized form
-     * of the current path.
-     *
-     * @return the location of the modification.
+     * {@inheritDoc}
      */
     public String getLocation() {
         return getProperty(PN_LOCATION, String.class);
@@ -340,6 +331,11 @@ public abstract class AbstractPostResponse implements PostResponse {
      * Returns the generic response property with the given name and type or
      * <code>null</code> if no such property exists or the property is not of
      * the requested type.
+     * @param name the name of the requetested property
+     * @param type the type of the parameter which should be returned
+     * @param <Type> the return type
+     * @return the property as the requested type or null if not available at all or not
+     *            in the requested type
      */
     @SuppressWarnings("unchecked")
     protected <Type> Type getProperty(String name, Class<Type> type) {
@@ -354,11 +350,17 @@ public abstract class AbstractPostResponse implements PostResponse {
     /**
      * Returns the generic response property with the given name and type or
      * <code>null</code> if no such property exists.
+     * @param name the name of the response property
+     * @return the requested property (might be null)
      */
     protected Object getProperty(String name) {
         return properties.get(name);
     }
     
+    /**
+     * determines if the referer has a proper referer including protocol
+     * @return true if HTTP or HTTPS protocol information is available in the referer
+     */
     protected boolean isSafeReferer(){
         String referer = getReferer();
         if (referer.startsWith("http://") || referer.startsWith("https://")) {
diff --git a/src/main/java/org/apache/sling/servlets/post/AbstractSlingPostOperation.java b/src/main/java/org/apache/sling/servlets/post/AbstractSlingPostOperation.java
index 28b55a8..69c1320 100644
--- a/src/main/java/org/apache/sling/servlets/post/AbstractSlingPostOperation.java
+++ b/src/main/java/org/apache/sling/servlets/post/AbstractSlingPostOperation.java
@@ -43,10 +43,10 @@ public abstract class AbstractSlingPostOperation extends AbstractPostOperation
 
     /**
      *
-     * @param request
-     * @param response
-     * @param changes
-     * @throws RepositoryException
+     * @param request the request
+     * @param response the response
+     * @param changes all changes
+     * @throws RepositoryException in case of problems
      */
     protected abstract void doRun(SlingHttpServletRequest request,
             HtmlResponse response, List<Modification> changes)
diff --git a/src/main/java/org/apache/sling/servlets/post/Modification.java b/src/main/java/org/apache/sling/servlets/post/Modification.java
index 7c01471..5d2891b 100644
--- a/src/main/java/org/apache/sling/servlets/post/Modification.java
+++ b/src/main/java/org/apache/sling/servlets/post/Modification.java
@@ -49,6 +49,7 @@ public class Modification {
      * Records a 'modified' change
      *
      * @param path path of the item that was modified
+     * @return the modification
      */
     public static Modification onModified(String path) {
         return onChange(ModificationType.MODIFY, path);
@@ -58,6 +59,7 @@ public class Modification {
      * Records a 'created' change
      *
      * @param path path of the item that was created
+     * @return the modification
      */
     public static Modification onCreated(String path) {
         return onChange(ModificationType.CREATE, path);
@@ -67,6 +69,7 @@ public class Modification {
      * Records a 'deleted' change
      *
      * @param path path of the item that was deleted
+     * @return the modification
      */
     public static Modification onDeleted(String path) {
         return onChange(ModificationType.DELETE, path);
@@ -80,6 +83,7 @@ public class Modification {
      *
      * @param srcPath source path of the node that was moved
      * @param dstPath destination path of the node that was moved.
+     * @return the modification
      */
     public static Modification onMoved(String srcPath, String dstPath) {
         return onChange(ModificationType.MOVE, srcPath, dstPath);
@@ -93,6 +97,7 @@ public class Modification {
      *
      * @param srcPath source path of the node that was copied
      * @param dstPath destination path of the node that was copied.
+     * @return the modification
      */
     public static Modification onCopied(String srcPath, String dstPath) {
         return onChange(ModificationType.COPY, srcPath, dstPath);
@@ -104,6 +109,7 @@ public class Modification {
      * @param orderedPath Path of the node that was reordered
      * @param beforeSibling Name of the sibling node before which the source node has
      *            been inserted.
+     * @return the modification
      */
     public static Modification onOrder(String orderedPath, String beforeSibling) {
         return onChange(ModificationType.ORDER, orderedPath, beforeSibling);
diff --git a/src/main/java/org/apache/sling/servlets/post/PostOperation.java b/src/main/java/org/apache/sling/servlets/post/PostOperation.java
index 76a7131..e09811b 100644
--- a/src/main/java/org/apache/sling/servlets/post/PostOperation.java
+++ b/src/main/java/org/apache/sling/servlets/post/PostOperation.java
@@ -33,7 +33,7 @@ import org.apache.sling.servlets.post.exceptions.TemporaryPersistenceException;
  * {@link #PROP_OPERATION_NAME} registration property giving the name(s) of the
  * operations supported by the service. The names will be used to find the
  * actual operation from the {@link SlingPostConstants#RP_OPERATION
- * <code>:operation</code>} request parameter.
+ * :operation} request parameter.
  * <p>
  * The Sling POST servlet itself provides various operations (see the
  * <code>OPERATION_</code> constants in the {@link SlingPostConstants}
@@ -45,7 +45,7 @@ import org.apache.sling.servlets.post.exceptions.TemporaryPersistenceException;
  * interface as well as operation postprocessing.
  * <p>
  * Implementors of this interface are advised to extend the
- * {@link AbstractPostOperation} class to benefit from various precossings
+ * {@link AbstractPostOperation} class to benefit from various processings
  * implemented by that abstract class.
  */
 public interface PostOperation {
@@ -75,14 +75,18 @@ public interface PostOperation {
      * @param processors The {@link SlingPostProcessor} services to be called
      *            after applying the operation. This may be <code>null</code> if
      *            there are none.
-     * @throws PersistenceException 
+     * @throws PersistenceException when the commit fails 
      * @throws org.apache.sling.api.resource.ResourceNotFoundException May be
      *             thrown if the operation requires an existing request
      *             resource. If this exception is thrown the Sling POST servlet
      *             sends back a <code>404/NOT FOUND</code> response to the
      *             client.
      * @throws org.apache.sling.api.SlingException May be thrown if an error
-     *             occurrs running the operation.
+     *             Occurs running the operation.
+     * @throws PreconditionViolatedPersistenceException when a necessary precondition failed,
+     *             and a retry without further changes doesn't make sense.
+     * @throws TemporaryPersistenceException when a commit failed, but a retry could make
+     *             the operation work successfully.
      */
     void run(SlingHttpServletRequest request, PostResponse response,
             SlingPostProcessor[] processors) throws PreconditionViolatedPersistenceException, TemporaryPersistenceException, PersistenceException;
diff --git a/src/main/java/org/apache/sling/servlets/post/PostResponse.java b/src/main/java/org/apache/sling/servlets/post/PostResponse.java
index 5c8d370..b4d0bcc 100644
--- a/src/main/java/org/apache/sling/servlets/post/PostResponse.java
+++ b/src/main/java/org/apache/sling/servlets/post/PostResponse.java
@@ -36,16 +36,19 @@ public interface PostResponse {
 
     /**
      * Sets the referer property
+     * @param referer the referer
      */
     public void setReferer(String referer);
 
     /**
      * Returns the referer previously set by {@link #setReferer(String)}
+     * @return the referer
      */
     public String getReferer();
 
     /**
      * Sets the absolute path of the item upon which the request operated.
+     * @param path the path
      */
     public void setPath(String path);
 
@@ -54,11 +57,13 @@ public interface PostResponse {
      * <p>
      * If the {@link #setPath(String)} method has not been called yet, this
      * method returns <code>null</code>.
+     * @return the path (might be null)
      */
     public String getPath();
 
     /**
      * Sets whether the request was a create request or not.
+     * @param isCreateRequest true if the request was a create request
      */
     public void setCreateRequest(boolean isCreateRequest);
 
@@ -67,6 +72,7 @@ public interface PostResponse {
      * <p>
      * Before calling the {@link #setCreateRequest(boolean)} method, this method
      * always returns <code>false</code>.
+     * @return if this was a create request
      */
     public boolean isCreateRequest();
 
@@ -74,7 +80,7 @@ public interface PostResponse {
      * Sets the location of this modification. This is the externalized form of
      * the {@link #getPath() current path}.
      *
-     * @param location
+     * @param location the location
      */
     public void setLocation(String location);
 
@@ -83,12 +89,14 @@ public interface PostResponse {
      * <p>
      * If the {@link #setLocation(String)} method has not been called yet, this
      * method returns <code>null</code>.
+     * @return the location
      */
     public String getLocation();
 
     /**
      * Sets the parent location of the modification. This is the externalized
      * form of the parent node of the {@link #getPath() current path}.
+     * @param parentLocation the parent location of the modification
      */
     public void setParentLocation(String parentLocation);
 
@@ -97,6 +105,7 @@ public interface PostResponse {
      * <p>
      * If the {@link #setParentLocation(String)} method has not been called yet,
      * this method returns <code>null</code>.
+     * @return the parent location
      */
     public String getParentLocation();
 
@@ -122,17 +131,20 @@ public interface PostResponse {
      * an error, the response is assumed to be unsuccessful and 500 is returned.
      * If there is no error, the response is assumed to be successful and 200 is
      * returned.
+     * @return the status code
      */
     public int getStatusCode();
 
     /**
      * Returns the status message or <code>null</code> if no has been set with
      * the {@link #setStatus(int, String)} method.
+     * @return the status message (might be null)
      */
     public String getStatusMessage();
 
     /**
      * Sets the recorded error causing the operation to fail.
+     * @param error the throwable
      */
     public void setError(Throwable error);
 
@@ -146,6 +158,7 @@ public interface PostResponse {
     /**
      * Returns <code>true</code> if no {@link #getError() error} is set and if
      * the {@link #getStatusCode() status code} is one of the 2xx codes.
+     * @return true if the status code is 2xx
      */
     public boolean isSuccessful();
 
diff --git a/src/main/java/org/apache/sling/servlets/post/SlingPostOperation.java b/src/main/java/org/apache/sling/servlets/post/SlingPostOperation.java
index 3aa490b..cf681dd 100644
--- a/src/main/java/org/apache/sling/servlets/post/SlingPostOperation.java
+++ b/src/main/java/org/apache/sling/servlets/post/SlingPostOperation.java
@@ -33,7 +33,7 @@ import org.apache.sling.servlets.post.exceptions.TemporaryPersistenceException;
  * {@link #PROP_OPERATION_NAME} registration property giving the name(s) of the
  * operations supported by the service. The names will be used to find the
  * actual operation from the {@link SlingPostConstants#RP_OPERATION
- * <code>:operation</code>} request parameter.
+ * :operation} request parameter.
  * <p>
  * The Sling default POST servlet defines the <code>copy</code>,
  * <code>move</code> and <code>delete</code> operation names. These names should
diff --git a/src/main/java/org/apache/sling/servlets/post/impl/helper/Chunk.java b/src/main/java/org/apache/sling/servlets/post/impl/helper/Chunk.java
index b95e079..60b5d41 100644
--- a/src/main/java/org/apache/sling/servlets/post/impl/helper/Chunk.java
+++ b/src/main/java/org/apache/sling/servlets/post/impl/helper/Chunk.java
@@ -31,6 +31,7 @@ public class Chunk {
 
     /**
      * Return offset of the chunk.
+     * @return the offset
      */
     public long getOffset() {
         return offset;
@@ -38,6 +39,7 @@ public class Chunk {
 
     /**
      * Set offset value.
+     * @param offset the offset
      */
     public void setOffsetValue(long offset) {
         this.offset = offset;
@@ -45,6 +47,7 @@ public class Chunk {
 
     /**
      * Return length of the file parameter.
+     * @return the length
      */
     public long getLength() {
         return length;
@@ -52,6 +55,7 @@ public class Chunk {
 
     /**
      * Set length of file parameter.
+     * @param length the length
      */
     public void setLength(long length) {
         this.length = length;
@@ -61,6 +65,7 @@ public class Chunk {
      * Return true if request contains last chunk as a result upload should be
      * finished. It is useful in scenarios where file streaming where file size
      * is not known in advance.
+     * @return if the chunk is completed
      */
     public boolean isCompleted() {
         return completed;
@@ -68,6 +73,7 @@ public class Chunk {
 
     /**
      * Set complete flag
+     * @param complete the complete flag
      */
     public void setCompleted(boolean complete) {
         this.completed = complete;
diff --git a/src/main/java/org/apache/sling/servlets/post/impl/helper/DateParser.java b/src/main/java/org/apache/sling/servlets/post/impl/helper/DateParser.java
index 2268b1c..d2cea2e 100644
--- a/src/main/java/org/apache/sling/servlets/post/impl/helper/DateParser.java
+++ b/src/main/java/org/apache/sling/servlets/post/impl/helper/DateParser.java
@@ -63,7 +63,6 @@ public class DateParser {
     /**
      * Parses the given source string and returns the respective calendar
      * instance. If no format matches returns <code>null</code>.
-     * <p/>
      *
      * @param source date time source string
      * @return calendar representation of the source or <code>null</code>
@@ -90,7 +89,6 @@ public class DateParser {
      * Parses the given source strings and returns the respective calendar
      * instances. If no format matches for any of the sources
      * returns <code>null</code>.
-     * <p/>
      *
      * @param sources date time source strings
      * @return calendar representations of the source or <code>null</code>
diff --git a/src/main/java/org/apache/sling/servlets/post/impl/helper/JCRSupport.java b/src/main/java/org/apache/sling/servlets/post/impl/helper/JCRSupport.java
index c09cf04..ef0c5b6 100644
--- a/src/main/java/org/apache/sling/servlets/post/impl/helper/JCRSupport.java
+++ b/src/main/java/org/apache/sling/servlets/post/impl/helper/JCRSupport.java
@@ -151,8 +151,15 @@ public class JCRSupport {
     /**
      * Stores property value(s) as reference(s). Will parse the reference(s) from the string
      * value(s) in the {@link RequestProperty}.
-     *
+     * 
+     * @param resource resource
+     * @param node the node
+     * @param name the name
+     * @param values the value
+     * @param type the type
+     * @param multiValued if multiValued
      * @return true only if parsing was successful and the property was actually changed
+     * @throws PersistenceException if the operation cannot be executed
      */
     public Modification storeAsReference(
             final Resource resource,
diff --git a/src/main/java/org/apache/sling/servlets/post/impl/helper/JCRSupportImpl.java b/src/main/java/org/apache/sling/servlets/post/impl/helper/JCRSupportImpl.java
index 07179f2..7d0eb3d 100644
--- a/src/main/java/org/apache/sling/servlets/post/impl/helper/JCRSupportImpl.java
+++ b/src/main/java/org/apache/sling/servlets/post/impl/helper/JCRSupportImpl.java
@@ -69,11 +69,9 @@ public class JCRSupportImpl {
      * nodes | N | at a specific position, N being an integer &lt;/xmp&gt;
      *
      * @param request The http request
-     * @param item node to order
-     * @param changes The list of modifications
-     * @throws RepositoryException if an error occurs
-     * @throws PreconditionViolatedPersistenceException 
-     * @throws TemporaryPersistenceException 
+     * @param resource the resource to order
+     * @param changes the list of modifications
+     * @throws PersistenceException in case the operation is not successful 
      */
     public void orderNode(final SlingHttpServletRequest request,
             final Resource resource,
@@ -371,10 +369,7 @@ public class JCRSupportImpl {
     }
 
     /**
-     * Stores property value(s) as reference(s). Will parse the reference(s) from the string
-     * value(s) in the {@link RequestProperty}.
-     *
-     * @return A modification only if parsing was successful and the property was actually changed
+     * {@inheritDoc}
      */
     public Modification storeAsReference(
             final Object n,
@@ -483,10 +478,10 @@ public class JCRSupportImpl {
      * @param name The name of the newly created item. If this is
      *            <code>null</code> the new item gets the same name as the
      *            <code>src</code> item.
+     * @return the name of the newly created object
      * @throws PersistenceException May be thrown in case of any problem copying
      *             the content.
-     * @throws PreconditionViolatedPersistenceException 
-     * @throws TemporaryPersistenceException
+     * @throws PersistenceException in case something fails
      * @see #copy(Node, Node, String)
      * @see #copy(Property, Node, String)
      */
@@ -565,8 +560,14 @@ public class JCRSupportImpl {
         return dst;
     }
 
-    /** @return true if src is an ancestor node of dest, or if
-     *  both are the same node */
+    /** 
+     * determines if the 2 nodes are in ancestor relationship or identical
+     * @param src one node
+     * @param dest the other node
+     * @return true if src is an ancestor node of dest, or if
+     *      both are the same node 
+     * @throws RepositoryException if something goes wrong
+     **/
     public static boolean isAncestorOrSameNode(Node src, Node dest) throws RepositoryException {
         if(src.getPath().equals("/")) {
             return true;
diff --git a/src/main/java/org/apache/sling/servlets/post/impl/helper/ReferenceParser.java b/src/main/java/org/apache/sling/servlets/post/impl/helper/ReferenceParser.java
index aa0690c..635db53 100644
--- a/src/main/java/org/apache/sling/servlets/post/impl/helper/ReferenceParser.java
+++ b/src/main/java/org/apache/sling/servlets/post/impl/helper/ReferenceParser.java
@@ -31,12 +31,12 @@ public class ReferenceParser {
     /**
      * Parses the given source string and returns the correct Value object.
      * If no node matches returns <code>null</code>.
-     * <p/>
      *
+     * @param session the session
      * @param value a path or UUID
      * @param weak true to create a WeakReference value
      * @return the value or <code>null</code>
-     * @throws RepositoryException
+     * @throws RepositoryException in case of problems
      */
     public static Value parse(Session session, String value, boolean weak) throws RepositoryException {
         Node n = parse(session, value);
@@ -50,13 +50,12 @@ public class ReferenceParser {
      * Parses the given source strings and returns the respective reference value
      * instances. If no node matches for any of the sources
      * returns <code>null</code>.
-     * <p/>
      *
+     * @param session the session
      * @param values path or UUID strings
-     * @param factory the value factory
      * @param weak true to create a WeakReference value
      * @return the values or <code>null</code>
-     * @throws RepositoryException
+     * @throws RepositoryException in case of problems
      */
     public static Value[] parse(Session session, String[] values, boolean weak) throws RepositoryException {
         Value ret[] = new Value[values.length];
diff --git a/src/main/java/org/apache/sling/servlets/post/impl/helper/RequestProperty.java b/src/main/java/org/apache/sling/servlets/post/impl/helper/RequestProperty.java
index a8b2d13..4aaccf9 100644
--- a/src/main/java/org/apache/sling/servlets/post/impl/helper/RequestProperty.java
+++ b/src/main/java/org/apache/sling/servlets/post/impl/helper/RequestProperty.java
@@ -221,7 +221,8 @@ public class RequestProperty {
     }
 
     /**
-     * Returns <code>true</code> if the repository item described by this is
+     * Determine the deletion status of this item
+     * @return <code>true</code> if the repository item described by this is
      * to be deleted before setting new content to it.
      */
     public boolean isDelete() {
@@ -251,7 +252,8 @@ public class RequestProperty {
     }
 
     /**
-     * Returns <code>true</code> if the content of this property is to be set
+     * If this is a target of a move operation
+     * @return <code>true</code> if the content of this property is to be set
      * by moving content from another repository item.
      *
      * @see #getRepositorySource()
@@ -261,7 +263,8 @@ public class RequestProperty {
     }
 
     /**
-     * Returns <code>true</code> if the content of this property is to be set
+     * if this is the source of a copy action
+     * @return <code>true</code> if the content of this property is to be set
      * by copying content from another repository item.
      *
      * @see #getRepositorySource()
@@ -271,7 +274,8 @@ public class RequestProperty {
     }
 
     /**
-     * Returns the absolute path of the repository item from which the content
+     * get the source of a copy or move operation
+     * @return the absolute path of the repository item from which the content
      * for this property is to be copied or moved.
      *
      * @see #hasRepositoryCopySource()
@@ -295,7 +299,8 @@ public class RequestProperty {
     }
 
     /**
-     * Returns whether this property is to be handled as a multi-value property
+     * determines if this property is handled as multi-value property
+     * @return whether this property is to be handled as a multi-value property
      * seen as set.
      */
     public boolean isPatch() {
@@ -303,7 +308,8 @@ public class RequestProperty {
     }
 
     /**
-     *  Return true if request is chunk upload.
+     *  it this is a chunk upload?
+     *  @return true if request is chunk upload.
      */
     public boolean isChunkUpload() {
         return chunk != null;
diff --git a/src/main/java/org/apache/sling/servlets/post/impl/helper/SlingFileUploadHandler.java b/src/main/java/org/apache/sling/servlets/post/impl/helper/SlingFileUploadHandler.java
index 470b580..d1ee4ff 100644
--- a/src/main/java/org/apache/sling/servlets/post/impl/helper/SlingFileUploadHandler.java
+++ b/src/main/java/org/apache/sling/servlets/post/impl/helper/SlingFileUploadHandler.java
@@ -53,37 +53,38 @@ import org.slf4j.LoggerFactory;
 
 /**
  * Handles file uploads.
- * <p/>
+ * <p>
  *
  * Simple example:
- * <xmp>
+ * 
+ * {@code
  *   <form action="/home/admin" method="POST" enctype="multipart/form-data">
  *     <input type="file" name="./portrait" />
  *   </form>
- * </xmp>
+ * }
  *
  * this will create a nt:file node below "/home/admin" if the node type of
  * "admin" is (derived from) nt:folder, a nt:resource node otherwise.
- * <p/>
+ * <p>
  *
  * Filename example:
- * <xmp>
+ * {@code
  *   <form action="/home/admin" method="POST" enctype="multipart/form-data">
  *     <input type="file" name="./*" />
  *   </form>
- * </xmp>
+ * }
  *
  * same as above, but uses the filename of the uploaded file as name for the
  * new node.
- * <p/>
+ * <p>
  *
  * Type hint example:
- * <xmp>
+ * {@code
  *   <form action="/home/admin" method="POST" enctype="multipart/form-data">
  *     <input type="file" name="./portrait" />
  *     <input type="hidden" name="./portrait@TypeHint" value="my:file" />
  *   </form>
- * </xmp>
+ * }
  *
  * this will create a new node with the type my:file below admin. if the hinted
  * type extends from nt:file an intermediate file node is created otherwise
@@ -417,6 +418,8 @@ public class SlingFileUploadHandler {
 
     /**
      * Delete all chunks saved within a resource. If no chunks exist, it is no-op.
+     * @param rsrc the resource
+     * @throws PersistenceException in case of problems
      */
     public void deleteChunks(final Resource rsrc) throws PersistenceException {
         final Resource chunkParent = getChunkParent(rsrc);
@@ -511,6 +514,7 @@ public class SlingFileUploadHandler {
      *
      * @param parent the parent node
      * @param prop the assembled property info
+     * @param changes the changes
      * @throws PersistenceException if an error occurs
      */
     public void setFile(final Resource parent, final RequestProperty prop, final List<Modification> changes)
diff --git a/src/main/java/org/apache/sling/servlets/post/impl/helper/SlingPropertyValueHandler.java b/src/main/java/org/apache/sling/servlets/post/impl/helper/SlingPropertyValueHandler.java
index 50abeb8..0ac27d9 100644
--- a/src/main/java/org/apache/sling/servlets/post/impl/helper/SlingPropertyValueHandler.java
+++ b/src/main/java/org/apache/sling/servlets/post/impl/helper/SlingPropertyValueHandler.java
@@ -73,6 +73,9 @@ public class SlingPropertyValueHandler {
 
     /**
      * Constructs a property value handler
+     * @param dateParser the dateParser
+     * @param jcrSupport the jcrSupport
+     * @param changes the changes 
      */
     public SlingPropertyValueHandler(final DateParser dateParser,
             final JCRSupport jcrSupport,
@@ -94,12 +97,12 @@ public class SlingPropertyValueHandler {
      * the field name but no value.
      *
      * html example for testing:
-     * <xmp>
+     * {@code
      *   <input type="hidden" name="created"/>
      *   <input type="hidden" name="lastModified"/>
      *   <input type="hidden" name="createdBy" />
      *   <input type="hidden" name="lastModifiedBy"/>
-     * </xmp>
+     * }
      *
      * @param parent the parent node
      * @param prop the request property
diff --git a/src/main/java/org/apache/sling/servlets/post/impl/helper/StreamedChunk.java b/src/main/java/org/apache/sling/servlets/post/impl/helper/StreamedChunk.java
index 1283acb..1129040 100644
--- a/src/main/java/org/apache/sling/servlets/post/impl/helper/StreamedChunk.java
+++ b/src/main/java/org/apache/sling/servlets/post/impl/helper/StreamedChunk.java
@@ -141,7 +141,7 @@ public class StreamedChunk {
      * @param fileResource the file request.
      * @param changes changes that were made.
      * @return the jcr:content sub node.
-     * @throws PersistenceException
+     * @throws PersistenceException in case of persistence issues
      */
     public Resource store(Resource fileResource, List<Modification> changes) throws PersistenceException {
         Resource result = fileResource.getChild(JcrConstants.JCR_CONTENT);
diff --git a/src/main/java/org/apache/sling/servlets/post/impl/operations/AbstractCopyMoveOperation.java b/src/main/java/org/apache/sling/servlets/post/impl/operations/AbstractCopyMoveOperation.java
index f6574b0..e650508 100644
--- a/src/main/java/org/apache/sling/servlets/post/impl/operations/AbstractCopyMoveOperation.java
+++ b/src/main/java/org/apache/sling/servlets/post/impl/operations/AbstractCopyMoveOperation.java
@@ -140,19 +140,21 @@ abstract class AbstractCopyMoveOperation extends AbstractPostOperation {
 
     /**
      * Returns a short name to be used in log and status messages.
+     * @return the name of the operation
      */
     protected abstract String getOperationName();
 
     /**
      * Actually executes the operation.
      *
-     * @param response The <code>HtmlResponse</code> used to record success of
-     *            the operation.
+     * @param changes the changes to execute
      * @param source The source item to act upon.
      * @param destParent The absolute path of the parent of the target item.
      * @param destName The name of the target item inside the
      *            <code>destParent</code>. If <code>null</code> the name of
      *            the <code>source</code> is used as the target item name.
+     * @param versioningConfiguration the configuration for versioning
+     * @return the resource which results of this operation
      * @throws PersistenceException May be thrown if an error occurs executing
      *             the operation.
      */
diff --git a/src/main/java/org/apache/sling/servlets/post/impl/operations/AbstractCreateOperation.java b/src/main/java/org/apache/sling/servlets/post/impl/operations/AbstractCreateOperation.java
index 036de5b..851c743 100644
--- a/src/main/java/org/apache/sling/servlets/post/impl/operations/AbstractCreateOperation.java
+++ b/src/main/java/org/apache/sling/servlets/post/impl/operations/AbstractCreateOperation.java
@@ -130,6 +130,11 @@ abstract class AbstractCreateOperation extends AbstractPostOperation {
     /**
      * Create resource(s) according to current request
      *
+     * @param resolver the resourceResolver to use
+     * @param reqProperties required properties
+     * @param response the response
+     * @param changes the changes to apply
+     * @param versioningConfiguration versioning configuration
      * @throws PersistenceException if a resource error occurs
      */
     protected void processCreate(final ResourceResolver resolver,
@@ -216,6 +221,9 @@ abstract class AbstractCreateOperation extends AbstractPostOperation {
     /**
      * Collects the properties that form the content to be written back to the
      * resource tree.
+     * @param request the request
+     * @param response the response
+     * @return the collected properties
      */
     protected Map<String, RequestProperty> collectContent(
             final SlingHttpServletRequest request,
@@ -512,7 +520,11 @@ abstract class AbstractCreateOperation extends AbstractPostOperation {
      * Deep gets or creates a resource, parent-padding with default resources. If
      * the path is empty, the given parent resource is returned.
      *
+     * @param resolver the resource resolver to use
      * @param path path to resources that needs to be deep-created
+     * @param reqProperties the properties to add
+     * @param changes the changes to apply
+     * @param versioningConfiguration the versioning configuration
      * @return Resource at path
      * @throws PersistenceException if an error occurs
      * @throws IllegalArgumentException if the path is relative and parent is
diff --git a/src/main/java/org/apache/sling/servlets/post/impl/operations/DeleteOperation.java b/src/main/java/org/apache/sling/servlets/post/impl/operations/DeleteOperation.java
index 78c9847..37f5dc6 100644
--- a/src/main/java/org/apache/sling/servlets/post/impl/operations/DeleteOperation.java
+++ b/src/main/java/org/apache/sling/servlets/post/impl/operations/DeleteOperation.java
@@ -106,6 +106,8 @@ public class DeleteOperation extends AbstractPostOperation {
     /**
      * Return true if request is to delete chunks. To return true, request will
      * should parameter ":applyToChunks" and it should be true.
+     * @param request the request
+     * @return is the request is to delete chunks
      */
     protected boolean isDeleteChunkRequest(SlingHttpServletRequest request) {