Add missing javadoc for exceptions thrown for invalid arguments (#339)

Author: dvmarcilio

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

@@ -1181,7 +1181,8 @@ static String decodeUrl(final String url) {
      *
      * @param file The file to delete.
      * @return the given file.
-     * @throws IOException if the file cannot be deleted.
+     * @throws NullPointerException     if the parameter is {@code null}
+     * @throws IOException              if the file cannot be deleted.
      * @see File#delete()
      * @since 2.9.0
      */
@@ -1196,6 +1197,7 @@ public static File delete(final File file) throws IOException {
      *
      * @param directory directory to delete
      * @throws IOException              in case deletion is unsuccessful
+     * @throws NullPointerException     if the parameter is {@code null}
      * @throws IllegalArgumentException if {@code directory} is not a directory
      */
     public static void deleteDirectory(final File directory) throws IOException {
@@ -3119,8 +3121,8 @@ private static String[] toSuffixes(final String... extensions) {
      * </p>
      *
      * @param file the File to touch.
-     * @throws IOException if an I/O problem occurs.
-     * @throws IOException if setting the last-modified time failed.
+     * @throws NullPointerException if the parameter is {@code null}.
+     * @throws IOException          if setting the last-modified time failed or an I/O problem occurs.
      */
     public static void touch(final File file) throws IOException {
         Objects.requireNonNull(file, "file");

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

@@ -1770,7 +1770,8 @@ public static int read(final InputStream input, final byte[] buffer) throws IOEx
      * @param offset initial offset into buffer
      * @param length length to read, must be >= 0
      * @return actual length read; may be less than requested if EOF was reached
-     * @throws IOException if a read error occurs
+     * @throws IllegalArgumentException if length is negative
+     * @throws IOException              if a read error occurs
      * @since 2.2
      */
     public static int read(final InputStream input, final byte[] buffer, final int offset, final int length)
@@ -1842,7 +1843,8 @@ public static int read(final Reader reader, final char[] buffer) throws IOExcept
      * @param offset initial offset into buffer
      * @param length length to read, must be >= 0
      * @return actual length read; may be less than requested if EOF was reached
-     * @throws IOException if a read error occurs
+     * @throws IllegalArgumentException if length is negative
+     * @throws IOException              if a read error occurs
      * @since 2.2
      */
     public static int read(final Reader reader, final char[] buffer, final int offset, final int length)

src/main/java/org/apache/commons/io/file/PathUtils.java

@@ -753,7 +753,8 @@ public static boolean fileContentEquals(final Path path1, final Path path2, fina
      * @param paths the array of files to apply the filter to.
      *
      * @return a subset of {@code files} that is accepted by the file filter.
-     * @throws IllegalArgumentException if the filter is {@code null} or {@code files} contains a {@code null} value.
+     * @throws NullPointerException if the filter is {@code null}
+     * @throws IllegalArgumentException if {@code files} contains a {@code null} value.
      *
      * @since 2.9.0
      */
@@ -1552,6 +1553,7 @@ static Set<FileVisitOption> toFileVisitOptionSet(final FileVisitOption... fileVi
      * @return the given visitor.
      *
      * @throws IOException if an I/O error is thrown by a visitor method.
+     * @throws NullPointerException if the directory is {@code null}.
      */
     public static <T extends FileVisitor<? super Path>> T visitFileTree(final T visitor, final Path directory) throws IOException {
         requireExists(directory, "directory");
@@ -1692,6 +1694,7 @@ private static <R> R withPosixFileAttributes(final Path path, final LinkOption[]
      * @param openOptions options How to open the file.
      * @return The given path.
      * @throws IOException if an I/O error occurs writing to or creating the file.
+     * @throws NullPointerException if either {@code path} or {@code charSequence} is {@code null}.
      * @since 2.12.0
      */
     public static Path writeString(final Path path, final CharSequence charSequence, final Charset charset, final OpenOption... openOptions)

src/test/java/org/apache/commons/io/FileUtilsDeleteDirectoryBaseTest.java

@@ -18,6 +18,7 @@
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
 import java.io.File;
@@ -249,4 +250,9 @@ public void testDeletesRegular() throws Exception {
         assertEquals(0, top.list().length);
     }
 
+    @Test
+    public void testDeleteDirectoryNullArgument() {
+        assertThrows(NullPointerException.class, () -> FileUtils.deleteDirectory(null));
+    }
+
 }

src/test/java/org/apache/commons/io/FileUtilsTest.java

@@ -2687,6 +2687,8 @@ public void testToFileUtf8() throws Exception {
 
     @Test
     public void testTouch() throws IOException {
+        assertThrows(NullPointerException.class, () -> FileUtils.touch(null));
+
         final File file = new File(tempDirFile, "touch.txt");
         if (file.exists()) {
             file.delete();