Javadoc. Remove Subversion's "@Version $Id$".

Author: Gary Gregory

src/main/java/org/apache/commons/io/DirectoryWalker.java

@@ -33,8 +33,10 @@
  * limit the files and directories visited.
  * Commons IO supplies many common filter implementations in the
  * <a href="filefilter/package-summary.html"> filefilter</a> package.
+ * </p>
  * <p>
  * The following sections describe:
+ * </p>
  *   <ul>
  *      <li><a href="#example">1. Example Implementation</a> - example
  *          <code>FileCleaner</code> implementation.</li>
@@ -82,20 +84,25 @@
  *
  * <h3 id="filter">2. Filter Example</h3>
  *
+ * <p>
  * Choosing which directories and files to process can be a key aspect
  * of using this class. This information can be setup in three ways,
  * via three different constructors.
+ * </p>
  * <p>
  * The first option is to visit all directories and files.
  * This is achieved via the no-args constructor.
+ * </p>
  * <p>
  * The second constructor option is to supply a single {@link FileFilter}
  * that describes the files and directories to visit. Care must be taken
  * with this option as the same filter is used for both directories
  * and files.
+ * </p>
  * <p>
  * For example, if you wanted all directories which are not hidden
  * and files which end in ".txt":
+ * </p>
  * <pre>
  *  public class FooDirectoryWalker extends DirectoryWalker {
  *    public FooDirectoryWalker(FileFilter filter) {
@@ -127,9 +134,11 @@
  * the correct <code>FileFilter</code>, something which is very easy to
  * get wrong when attempted manually, particularly when trying to
  * express constructs like 'any file in directories named docs'.
+ * </p>
  * <p>
  * For example, if you wanted all directories which are not hidden
  * and files which end in ".txt":
+ * </p>
  * <pre>
  *  public class FooDirectoryWalker extends DirectoryWalker {
  *    public FooDirectoryWalker(IOFileFilter dirFilter, IOFileFilter fileFilter) {
@@ -143,15 +152,20 @@
  *    FileFilterUtils.suffixFileFilter(".txt"),
  *  );
  * </pre>
+ * <p>
  * This is much simpler than the previous example, and is why it is the preferred
  * option for filtering.
+ * </p>
  *
  * <h3 id="cancel">3. Cancellation</h3>
  *
+ * <p>
  * The DirectoryWalker contains some of the logic required for cancel processing.
  * Subclasses must complete the implementation.
+ * </p>
  * <p>
  * What <code>DirectoryWalker</code> does provide for cancellation is:
+ * </p>
  * <ul>
  *    <li>{@link CancelException} which can be thrown in any of the
  *        <i>lifecycle</i> methods to stop processing.</li>
@@ -161,13 +175,15 @@
  * </ul>
  * <p>
  * Implementations need to provide:
+ * </p>
  * <ul>
  *    <li>The decision logic on whether to cancel processing or not.</li>
  *    <li>Constructing and throwing a {@link CancelException}.</li>
  *    <li>Custom cancel processing in the <code>handleCancelled()</code> method.
  * </ul>
  * <p>
  * Two possible scenarios are envisaged for cancellation:
+ * </p>
  * <ul>
  *    <li><a href="#external">3.1 External / Multi-threaded</a> - cancellation being
  *        decided/initiated by an external process.</li>
@@ -177,9 +193,11 @@
  * <p>
  * The following sections provide example implementations for these two different
  * scenarios.
+ * </p>
  *
  * <h4 id="external">3.1 External / Multi-threaded</h4>
  *
+ * <p>
  * This example provides a public <code>cancel()</code> method that can be
  * called by another thread to stop the processing. A typical example use-case
  * would be a cancel button on a GUI. Calling this method sets a
@@ -189,6 +207,7 @@
  * will cause the walk to stop immediately. The <code>handleCancelled()</code>
  * method will be the next, and last, callback method received once cancellation
  * has occurred.
+ * </p>
  *
  * <pre>
  *  public class FooDirectoryWalker extends DirectoryWalker {
@@ -211,9 +230,11 @@
  *
  * <h4 id="internal">3.2 Internal</h4>
  *
+ * <p>
  * This shows an example of how internal cancellation processing could be implemented.
  * <b>Note</b> the decision logic and throwing a {@link CancelException} could be implemented
  * in any of the <i>lifecycle</i> methods.
+ * </p>
  *
  * <pre>
  *  public class BarDirectoryWalker extends DirectoryWalker {
@@ -241,7 +262,7 @@
  * </pre>
  *
  * @since 1.3
- * @version $Id$
+ *
  */
 public abstract class DirectoryWalker<T> {
 
@@ -262,12 +283,13 @@ protected DirectoryWalker() {
     }
 
     /**
-     * Construct an instance with a filter and limit the <i>depth</i> navigated to.
+     * Constructs an instance with a filter and limit the <i>depth</i> navigated to.
      * <p>
      * The filter controls which files and directories will be navigated to as
      * part of the walk. The {@link FileFilterUtils} class is useful for combining
      * various filters together. A {@code null} filter means that no
      * filtering should occur and all files and directories will be visited.
+     * </p>
      *
      * @param filter  the filter to apply, null means visit all files
      * @param depthLimit  controls how <i>deep</i> the hierarchy is
@@ -279,13 +301,14 @@ protected DirectoryWalker(final FileFilter filter, final int depthLimit) {
     }
 
     /**
-     * Construct an instance with a directory and a file filter and an optional
+     * Constructs an instance with a directory and a file filter and an optional
      * limit on the <i>depth</i> navigated to.
      * <p>
      * The filters control which files and directories will be navigated to as part
      * of the walk. This constructor uses {@link FileFilterUtils#makeDirectoryOnly(IOFileFilter)}
      * and {@link FileFilterUtils#makeFileOnly(IOFileFilter)} internally to combine the filters.
      * A {@code null} filter means that no filtering should occur.
+     * </p>
      *
      * @param directoryFilter  the filter to apply to directories, null means visit all directories
      * @param fileFilter  the filter to apply to files, null means visit all files
@@ -311,10 +334,12 @@ protected DirectoryWalker(IOFileFilter directoryFilter, IOFileFilter fileFilter,
      * <p>
      * Users of this class do not need to call this method. This method will
      * be called automatically by another (public) method on the specific subclass.
+     * </p>
      * <p>
      * Writers of subclasses should call this method to start the directory walk.
      * Once called, this method will emit events as it walks the hierarchy.
      * The event methods have the prefix <code>handle</code>.
+     * </p>
      *
      * @param startDirectory  the directory to start from, not null
      * @param results  the collection of result objects, may be updated
@@ -379,6 +404,7 @@ private void walk(final File directory, final int depth, final Collection<T> res
      * automatically by the walk of the tree. However, sometimes a single method,
      * typically {@link #handleFile}, may take a long time to run. In that case,
      * you may wish to check for cancellation by calling this method.
+     * </p>
      *
      * @param file  the current file being processed
      * @param depth  the current file level (starting directory = 0)
@@ -399,6 +425,7 @@ protected final void checkIfCancelled(final File file, final int depth, final Co
      * This method should be implemented by those subclasses that want to
      * provide a public <code>cancel()</code> method available from another
      * thread. The design pattern for the subclass should be as follows:
+     * </p>
      * <pre>
      *  public class FooDirectoryWalker extends DirectoryWalker {
      *    private volatile boolean cancelled = false;
@@ -418,8 +445,10 @@ protected final void checkIfCancelled(final File file, final int depth, final Co
      * <p>
      * If this method returns true, then the directory walk is immediately
      * cancelled. The next callback method will be {@link #handleCancelled}.
+     * </p>
      * <p>
      * This implementation returns false.
+     * </p>
      *
      * @param file  the file or directory being processed
      * @param depth  the current directory level (starting directory = 0)
@@ -439,6 +468,7 @@ protected boolean handleIsCancelled(
      * obtained from the exception.
      * <p>
      * This implementation just re-throws the {@link CancelException}.
+     * </p>
      *
      * @param startDirectory  the directory that the walk started from
      * @param results  the collection of result objects, may be updated
@@ -457,6 +487,7 @@ protected void handleCancelled(final File startDirectory, final Collection<T> re
      * Overridable callback method invoked at the start of processing.
      * <p>
      * This implementation does nothing.
+     * </p>
      *
      * @param startDirectory  the directory to start from
      * @param results  the collection of result objects, may be updated
@@ -472,8 +503,10 @@ protected void handleStart(final File startDirectory, final Collection<T> result
      * This method returns a boolean to indicate if the directory should be examined or not.
      * If you return false, the entire directory and any subdirectories will be skipped.
      * Note that this functionality is in addition to the filtering by file filter.
+     * </p>
      * <p>
      * This implementation does nothing and returns true.
+     * </p>
      *
      * @param directory  the current directory being processed
      * @param depth  the current directory level (starting directory = 0)
@@ -491,6 +524,7 @@ protected boolean handleDirectory(final File directory, final int depth, final C
      * Overridable callback method invoked at the start of processing each directory.
      * <p>
      * This implementation does nothing.
+     * </p>
      *
      * @param directory  the current directory being processed
      * @param depth  the current directory level (starting directory = 0)
@@ -506,6 +540,7 @@ protected void handleDirectoryStart(final File directory, final int depth, final
      * Overridable callback method invoked with the contents of each directory.
      * <p>
      * This implementation returns the files unchanged
+     * </p>
      *
      * @param directory  the current directory being processed
      * @param depth  the current directory level (starting directory = 0)
@@ -523,6 +558,7 @@ protected File[] filterDirectoryContents(final File directory, final int depth,
      * Overridable callback method invoked for each (non-directory) file.
      * <p>
      * This implementation does nothing.
+     * </p>
      *
      * @param file  the current file being processed
      * @param depth  the current directory level (starting directory = 0)
@@ -537,6 +573,7 @@ protected void handleFile(final File file, final int depth, final Collection<T>
      * Overridable callback method invoked for each restricted directory.
      * <p>
      * This implementation does nothing.
+     * </p>
      *
      * @param directory  the restricted directory
      * @param depth  the current directory level (starting directory = 0)
@@ -552,6 +589,7 @@ protected void handleRestricted(final File directory, final int depth, final Col
      * Overridable callback method invoked at the end of processing each directory.
      * <p>
      * This implementation does nothing.
+     * </p>
      *
      * @param directory  the directory being processed
      * @param depth  the current directory level (starting directory = 0)
@@ -567,6 +605,7 @@ protected void handleDirectoryEnd(final File directory, final int depth, final C
      * Overridable callback method invoked at the end of processing.
      * <p>
      * This implementation does nothing.
+     * </p>
      *
      * @param results  the collection of result objects, may be updated
      * @throws IOException if an I/O Error occurs
@@ -617,7 +656,7 @@ public CancelException(final String message, final File file, final int depth) {
         }
 
         /**
-         * Return the file when the operation was cancelled.
+         * Returns the file when the operation was cancelled.
          *
          * @return the file when the operation was cancelled
          */
@@ -626,7 +665,7 @@ public File getFile() {
         }
 
         /**
-         * Return the depth when the operation was cancelled.
+         * Returns the depth when the operation was cancelled.
          *
          * @return the depth when the operation was cancelled
          */