(doc) [IO-484] Fix incorrect FilenameUtils documentation for null bytes

Author: Marcono1234

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

@@ -194,7 +194,8 @@ public class FilenameUtils {
      *
      * @param basePath  the base path to attach to, always treated as a path
      * @param fullFileNameToAdd  the fileName (or path) to attach to the base
-     * @return the concatenated path, or null if invalid.  Null bytes inside string will be removed
+     * @return the concatenated path, or null if invalid
+     * @throws IllegalArgumentException if the result path contains null bytes
      */
     public static String concat(final String basePath, final String fullFileNameToAdd) {
         final int prefix = getPrefixLength(fullFileNameToAdd);
@@ -260,8 +261,10 @@ public static boolean directoryContains(final String canonicalParent, final Stri
      * @param fileName  the fileName
      * @param includeSeparator  true to include the end separator
      * @return the path
+     * @throws IllegalArgumentException if the result path contains null bytes
      */
     private static String doGetFullPath(final String fileName, final boolean includeSeparator) {
+        // TODO: Does not (indirectly) call requireNonNullChars in all cases for result
         if (fileName == null) {
             return null;
         }
@@ -291,7 +294,8 @@ private static String doGetFullPath(final String fileName, final boolean include
      *
      * @param fileName  the fileName
      * @param separatorAdd  0 to omit the end separator, 1 to return it
-     * @return the path. Null bytes inside string will be removed
+     * @return the path
+     * @throws IllegalArgumentException if the result path contains null bytes
      */
     private static String doGetPath(final String fileName, final int separatorAdd) {
         if (fileName == null) {
@@ -315,7 +319,8 @@ private static String doGetPath(final String fileName, final int separatorAdd) {
      * @param fileName  the fileName
      * @param separator The separator character to use
      * @param keepSeparator  true to keep the final separator
-     * @return the normalized fileName. Null bytes inside string will be removed.
+     * @return the normalized fileName
+     * @throws IllegalArgumentException if the fileName contains null bytes
      */
     private static String doNormalize(final String fileName, final char separator, final boolean keepSeparator) {
         if (fileName == null) {
@@ -447,6 +452,9 @@ public static boolean equals(String fileName1, String fileName2, final boolean n
         if (fileName1 == null || fileName2 == null) {
             return fileName1 == null && fileName2 == null;
         }
+        // TODO: Should IllegalArgumentException thrown by `normalize` for null bytes be
+        // handled? (and for example `false` be returned instead); If not, have to mention it
+        // in javadoc of this method and callers
         if (normalized) {
             fileName1 = normalize(fileName1);
             if (fileName1 == null) {
@@ -565,8 +573,8 @@ private static int getAdsCriticalOffset(final String fileName) {
      * </p>
      *
      * @param fileName  the fileName to query, null returns null
-     * @return the name of the file without the path, or an empty string if none exists. Null bytes inside string
-     * will be removed
+     * @return the name of the file without the path, or an empty string if none exists
+     * @throws IllegalArgumentException if the fileName contains null bytes
      */
     public static String getBaseName(final String fileName) {
         return removeExtension(getName(fileName));
@@ -610,6 +618,7 @@ public static String getExtension(final String fileName) throws IllegalArgumentE
         if (index == NOT_FOUND) {
             return EMPTY_STRING;
         }
+        // TODO: Should check for null bytes?
         return fileName.substring(index + 1);
     }
 
@@ -639,6 +648,7 @@ public static String getExtension(final String fileName) throws IllegalArgumentE
      *
      * @param fileName  the fileName to query, null returns null
      * @return the path of the file, an empty string if none exists, null if invalid
+     * @throws IllegalArgumentException if the result path contains null bytes
      */
     public static String getFullPath(final String fileName) {
         return doGetFullPath(fileName, true);
@@ -671,6 +681,7 @@ public static String getFullPath(final String fileName) {
      *
      * @param fileName  the fileName to query, null returns null
      * @return the path of the file, an empty string if none exists, null if invalid
+     * @throws IllegalArgumentException if the result path contains null bytes
      */
     public static String getFullPathNoEndSeparator(final String fileName) {
         return doGetFullPath(fileName, false);
@@ -693,8 +704,8 @@ public static String getFullPathNoEndSeparator(final String fileName) {
      * </p>
      *
      * @param fileName  the fileName to query, null returns null
-     * @return the name of the file without the path, or an empty string if none exists.
-     * Null bytes inside string will be removed
+     * @return the name of the file without the path, or an empty string if none exists
+     * @throws IllegalArgumentException if the fileName contains null bytes
      */
     public static String getName(final String fileName) {
         if (fileName == null) {
@@ -726,8 +737,8 @@ public static String getName(final String fileName) {
      * </p>
      *
      * @param fileName  the fileName to query, null returns null
-     * @return the path of the file, an empty string if none exists, null if invalid.
-     * Null bytes inside string will be removed
+     * @return the path of the file, an empty string if none exists, null if invalid
+     * @throws IllegalArgumentException if the result path contains null bytes
      */
     public static String getPath(final String fileName) {
         return doGetPath(fileName, 1);
@@ -757,8 +768,8 @@ public static String getPath(final String fileName) {
      * </p>
      *
      * @param fileName  the fileName to query, null returns null
-     * @return the path of the file, an empty string if none exists, null if invalid.
-     * Null bytes inside string will be removed
+     * @return the path of the file, an empty string if none exists, null if invalid
+     * @throws IllegalArgumentException if the result path contains null bytes
      */
     public static String getPathNoEndSeparator(final String fileName) {
         return doGetPath(fileName, 0);
@@ -793,7 +804,8 @@ public static String getPathNoEndSeparator(final String fileName) {
      * </p>
      *
      * @param fileName  the fileName to query, null returns null
-     * @return the prefix of the file, null if invalid. Null bytes inside string will be removed
+     * @return the prefix of the file, null if invalid
+     * @throws IllegalArgumentException if the result contains null bytes
      */
     public static String getPrefix(final String fileName) {
         if (fileName == null) {
@@ -987,7 +999,7 @@ private static boolean isEmpty(final String string) {
      * @param fileName  the fileName to query, null returns false
      * @param extensions  the extensions to check for, null checks for no extension
      * @return true if the fileName is one of the extensions
-     * @throws java.lang.IllegalArgumentException if the supplied fileName contains null bytes
+     * @throws IllegalArgumentException if the fileName contains null bytes
      */
     public static boolean isExtension(final String fileName, final Collection<String> extensions) {
         if (fileName == null) {
@@ -1017,7 +1029,7 @@ public static boolean isExtension(final String fileName, final Collection<String
      * @param fileName  the fileName to query, null returns false
      * @param extension  the extension to check for, null or empty checks for no extension
      * @return true if the fileName has the specified extension
-     * @throws java.lang.IllegalArgumentException if the supplied fileName contains null bytes
+     * @throws IllegalArgumentException if the fileName contains null bytes
      */
     public static boolean isExtension(final String fileName, final String extension) {
         if (fileName == null) {
@@ -1041,7 +1053,7 @@ public static boolean isExtension(final String fileName, final String extension)
      * @param fileName  the fileName to query, null returns false
      * @param extensions  the extensions to check for, null checks for no extension
      * @return true if the fileName is one of the extensions
-     * @throws java.lang.IllegalArgumentException if the supplied fileName contains null bytes
+     * @throws IllegalArgumentException if the fileName contains null bytes
      */
     public static boolean isExtension(final String fileName, final String... extensions) {
         if (fileName == null) {
@@ -1253,7 +1265,8 @@ private static boolean isValidHostName(final String name) {
      * (Note the file separator returned will be correct for Windows/Unix)
      *
      * @param fileName  the fileName to normalize, null returns null
-     * @return the normalized fileName, or null if invalid. Null bytes inside string will be removed
+     * @return the normalized fileName, or null if invalid
+     * @throws IllegalArgumentException if the fileName contains null bytes
      */
     public static String normalize(final String fileName) {
         return doNormalize(fileName, SYSTEM_NAME_SEPARATOR, true);
@@ -1300,7 +1313,8 @@ public static String normalize(final String fileName) {
      * @param fileName  the fileName to normalize, null returns null
      * @param unixSeparator {@code true} if a unix separator should
      * be used or {@code false} if a windows separator should be used.
-     * @return the normalized fileName, or null if invalid. Null bytes inside string will be removed
+     * @return the normalized fileName, or null if invalid
+     * @throws IllegalArgumentException if the fileName contains null bytes
      * @since 2.0
      */
     public static String normalize(final String fileName, final boolean unixSeparator) {
@@ -1346,7 +1360,8 @@ public static String normalize(final String fileName, final boolean unixSeparato
      * (Note the file separator returned will be correct for Windows/Unix)
      *
      * @param fileName  the fileName to normalize, null returns null
-     * @return the normalized fileName, or null if invalid. Null bytes inside string will be removed
+     * @return the normalized fileName, or null if invalid
+     * @throws IllegalArgumentException if the fileName contains null bytes
      */
     public static String normalizeNoEndSeparator(final String fileName) {
         return doNormalize(fileName, SYSTEM_NAME_SEPARATOR, false);
@@ -1392,7 +1407,8 @@ public static String normalizeNoEndSeparator(final String fileName) {
      * @param fileName  the fileName to normalize, null returns null
      * @param unixSeparator {@code true} if a unix separator should
      * be used or {@code false} if a windows separator should be used.
-     * @return the normalized fileName, or null if invalid. Null bytes inside string will be removed
+     * @return the normalized fileName, or null if invalid
+     * @throws IllegalArgumentException if the fileName contains null bytes
      * @since 2.0
      */
     public static String normalizeNoEndSeparator(final String fileName, final boolean unixSeparator) {
@@ -1415,6 +1431,7 @@ public static String normalizeNoEndSeparator(final String fileName, final boolea
      *
      * @param fileName  the fileName to query, null returns null
      * @return the fileName minus the extension
+     * @throws IllegalArgumentException if the fileName contains null bytes
      */
     public static String removeExtension(final String fileName) {
         if (fileName == null) {
@@ -1436,6 +1453,7 @@ public static String removeExtension(final String fileName) {
      *
      * @param path the path to check
      * @return The input
+     * @throws IllegalArgumentException if path contains null bytes
      */
     private static String requireNonNullChars(final String path) {
         if (path.indexOf(0) >= 0) {