Skip to content

Commit

Permalink
docs: edit various comments for typos and Sun javadoc conventions (#26)
Browse files Browse the repository at this point in the history
  • Loading branch information
@elharo
elharo authored Apr 12, 2020
1 parent c26ac49 commit 29e61f2
Showing 1 changed file with 63 additions and 64 deletions.
127 changes: 63 additions & 64 deletions src/main/java/org/apache/maven/shared/utils/io/FileUtils.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,7 @@ public class FileUtils
*/
protected FileUtils()
{
// This is a utility class. Normally dont instantiate
// This is a utility class. Normally don't instantiate
}

/**
Expand Down Expand Up @@ -134,7 +134,7 @@ protected FileUtils()
}

/**
* @return the default excludes pattern as list.
* @return the default excludes pattern as list
* @see #getDefaultExcludes()
*/
@Nonnull public static List<String> getDefaultExcludesAsList()
Expand All @@ -157,7 +157,7 @@ protected FileUtils()
* Matches the equally named unix command.
*
* @param filename the file path
* @return The directory portion excluding the ending file separator.
* @return the directory portion excluding the ending file separator
*/
@Nonnull public static String dirname( @Nonnull String filename )
{
Expand All @@ -169,7 +169,7 @@ protected FileUtils()
* Returns the filename portion of a file specification string.
*
* @param filename the file path
* @return The filename string with extension.
* @return the filename string with extension
*/
@Nonnull public static String filename( @Nonnull String filename )
{
Expand Down Expand Up @@ -212,10 +212,10 @@ protected FileUtils()
}

/**
* Check if a file exits.
* Check if a file exists.
*
* @param fileName the file path.
* @return true if file exists.
* @param fileName the file path
* @return true if file exists
*/
public static boolean fileExists( @Nonnull String fileName )
{
Expand All @@ -227,7 +227,7 @@ public static boolean fileExists( @Nonnull String fileName )
* Note: the file content is read with platform encoding.
*
* @param file the file path
* @return the file content using the platform encoding.
* @return the file content using the platform encoding
* @throws IOException if any
*/
@Nonnull public static String fileRead( @Nonnull String file )
Expand All @@ -239,7 +239,7 @@ public static boolean fileExists( @Nonnull String fileName )
/**
* @param file the file path
* @param encoding the wanted encoding
* @return the file content using the specified encoding.
* @return the file content using the specified encoding
* @throws IOException if any
*/
@Nonnull private static String fileRead( @Nonnull String file, @Nullable String encoding )
Expand All @@ -249,10 +249,10 @@ public static boolean fileExists( @Nonnull String fileName )
}

/**
* Note: the file content is read with platform encoding
* Note: the file content is read with platform encoding.
*
* @param file the file path
* @return the file content using the platform encoding.
* @return the file content using the platform encoding
* @throws IOException if any
*/
@Nonnull public static String fileRead( @Nonnull File file )
Expand All @@ -264,7 +264,7 @@ public static boolean fileExists( @Nonnull String fileName )
/**
* @param file the file path
* @param encoding the wanted encoding
* @return the file content using the specified encoding.
* @return the file content using the specified encoding
* @throws IOException if any
*/
@Nonnull public static String fileRead( @Nonnull File file, @Nullable String encoding )
Expand Down Expand Up @@ -303,9 +303,9 @@ public static boolean fileExists( @Nonnull String fileName )

/**
* @param file the file path
* @return the file content lines as String[] using the systems default encoding.
* An empty List if the file didn't exist.
* @throws IOException in case of failure.
* @return the file content lines as String[] using the system default encoding.
* An empty List if the file doesn't exist.
* @throws IOException in case of failure
*/
@Nonnull public static String[] fileReadArray( @Nonnull File file )
throws IOException
Expand All @@ -316,11 +316,11 @@ public static boolean fileExists( @Nonnull String fileName )
}

/**
* Appends data to a file. The file will be created if it does not exist.
* Note: the data is written with platform encoding
* Appends data to a file. The file is created if it does not exist.
* Note: the data is written with platform encoding.
*
* @param fileName The path of the file to write.
* @param data The content to write to the file.
* @param fileName the path of the file to write
* @param data the content to write to the file
* @throws IOException if any
*/
public static void fileAppend( @Nonnull String fileName, @Nonnull String data )
Expand All @@ -332,9 +332,9 @@ public static void fileAppend( @Nonnull String fileName, @Nonnull String data )
/**
* Appends data to a file. The file will be created if it does not exist.
*
* @param fileName The path of the file to write.
* @param encoding The encoding of the file.
* @param data The content to write to the file.
* @param fileName the path of the file to write
* @param encoding the encoding of the file
* @param data the content to write to the file
* @throws IOException if any
*/
public static void fileAppend( @Nonnull String fileName, @Nullable String encoding, @Nonnull String data )
Expand Down Expand Up @@ -365,8 +365,8 @@ public static void fileAppend( @Nonnull String fileName, @Nullable String encodi
* Writes data to a file. The file will be created if it does not exist.
* Note: the data is written with platform encoding
*
* @param fileName The path of the file to write.
* @param data The content to write to the file.
* @param fileName the path of the file to write
* @param data the content to write to the file
* @throws IOException if any
*/
public static void fileWrite( @Nonnull String fileName, @Nonnull String data )
Expand All @@ -378,9 +378,9 @@ public static void fileWrite( @Nonnull String fileName, @Nonnull String data )
/**
* Writes data to a file. The file will be created if it does not exist.
*
* @param fileName The path of the file to write.
* @param encoding The encoding of the file.
* @param data The content to write to the file.
* @param fileName the path of the file to write
* @param encoding the encoding of the file
* @param data the content to write to the file
* @throws IOException if any
*/
public static void fileWrite( @Nonnull String fileName, @Nullable String encoding, @Nonnull String data )
Expand All @@ -393,9 +393,9 @@ public static void fileWrite( @Nonnull String fileName, @Nullable String encodin
/**
* Writes data to a file. The file will be created if it does not exist.
*
* @param file The path of the file to write.
* @param encoding The encoding of the file.
* @param data The content to write to the file.
* @param file the path of the file to write
* @param encoding the encoding of the file
* @param data the content to write to the file
* @throws IOException if any
*/
public static void fileWrite( @Nonnull File file, @Nullable String encoding, @Nonnull String data )
Expand Down Expand Up @@ -426,8 +426,8 @@ public static void fileWrite( @Nonnull File file, @Nullable String encoding, @No
* Writes String array data to a file in the systems default encoding.
* The file will be created if it does not exist.
*
* @param file The path of the file to write.
* @param data The content to write to the file.
* @param file the path of the file to write
* @param data the content to write to the file
* @throws IOException if any
*/
public static void fileWriteArray( @Nonnull File file, @Nullable String... data )
Expand All @@ -437,11 +437,11 @@ public static void fileWriteArray( @Nonnull File file, @Nullable String... data
}

/**
* Writes String array data to a file. The file will be created if it does not exist.
* Writes String array data to a file. The file is created if it does not exist.
*
* @param file The path of the file to write.
* @param encoding The encoding of the file.
* @param data The content to write to the file.
* @param file the path of the file to write
* @param encoding the encoding of the file
* @param data the content to write to the file
* @throws IOException if any
*/
public static void fileWriteArray( @Nonnull File file, @Nullable String encoding, @Nullable String... data )
Expand Down Expand Up @@ -480,7 +480,7 @@ public static void fileWriteArray( @Nonnull File file, @Nullable String encoding
/**
* Deletes a file.
*
* @param fileName The path of the file to delete.
* @param fileName the path of the file to delete
*/
public static void fileDelete( @Nonnull String fileName )
{
Expand All @@ -494,9 +494,9 @@ public static void fileDelete( @Nonnull String fileName )
* <p/>
* The given extensions should be like "java" and not like ".java"
*
* @param directory The path of the directory.
* @param extensions an array of expected extensions.
* @return An array of files for the wanted extensions.
* @param directory the path of the directory
* @param extensions an array of expected extensions
* @return tn array of files for the wanted extensions
*/
public static String[] getFilesFromExtension( @Nonnull String directory, @Nonnull String... extensions )
{
Expand Down Expand Up @@ -524,7 +524,7 @@ public static String[] getFilesFromExtension( @Nonnull String directory, @Nonnul
continue;
}

// ok... transverse into this directory and get all the files... then combine
// ok... traverse into this directory and get all the files... then combine
// them with the current list.

String[] fetchFiles = getFilesFromExtension( currentFileName, extensions );
Expand Down Expand Up @@ -661,9 +661,9 @@ public static boolean contentEquals( @Nonnull final File file1, @Nonnull final F
/**
* Convert from a <code>URL</code> to a <code>File</code>.
*
* @param url File URL.
* @return The equivalent <code>File</code> object, or <code>null</code> if the URL's protocol
* is not <code>file</code>
* @param url file URL
* @return the equivalent <code>File</code> object, or <code>null</code> if the URL's protocol
* is not <code>file</code>
*/
@Nullable public static File toFile( @Nullable final URL url )
{
Expand Down Expand Up @@ -707,8 +707,7 @@ public static boolean contentEquals( @Nonnull final File file1, @Nonnull final F
}

/**
* Remove extension from filename.
* ie
* Remove extension from filename. E.g.
* <pre>
* foo.txt --> foo
* a\b\c.jpg --> a\b\c
Expand All @@ -732,8 +731,8 @@ public static boolean contentEquals( @Nonnull final File file1, @Nonnull final F
}

/**
* Get extension from filename.
* ie
* Get extension from filename. E.g.
*
* <pre>
* foo.txt --> "txt"
* a\b\c.jpg --> "jpg"
Expand All @@ -753,10 +752,10 @@ public static boolean contentEquals( @Nonnull final File file1, @Nonnull final F
* (and any parent directories) will be created. If a file <code>source</code> in
* <code>destinationDirectory</code> exists, it will be overwritten.
*
* @param source An existing <code>File</code> to copy.
* @param destinationDirectory A directory to copy <code>source</code> into.
* @throws java.io.FileNotFoundException if <code>source</code> isn't a normal file.
* @throws IllegalArgumentException if <code>destinationDirectory</code> isn't a directory.
* @param source an existing <code>File</code> to copy
* @param destinationDirectory a directory to copy <code>source</code> into
* @throws java.io.FileNotFoundException if <code>source</code> isn't a normal file
* @throws IllegalArgumentException if <code>destinationDirectory</code> isn't a directory
* @throws IOException if <code>source</code> does not exist, the file in
* <code>destinationDirectory</code> cannot be written to, or an IO error
* occurs during copying.
Expand All @@ -775,16 +774,16 @@ public static void copyFileToDirectory( @Nonnull final File source, @Nonnull fin
/**
* Copy file from source to destination only if source is newer than the target file.
* If <code>destinationDirectory</code> does not exist, it
* (and any parent directories) will be created. If a file <code>source</code> in
* <code>destinationDirectory</code> exists, it will be overwritten.
* (and any parent directories) is created. If a file <code>source</code> in
* <code>destinationDirectory</code> exists, it is overwritten.
*
* @param source An existing <code>File</code> to copy.
* @param destinationDirectory A directory to copy <code>source</code> into.
* @throws java.io.FileNotFoundException if <code>source</code> isn't a normal file.
* @throws IllegalArgumentException if <code>destinationDirectory</code> isn't a directory.
* @param source an existing <code>File</code> to copy
* @param destinationDirectory a directory to copy <code>source</code> into
* @throws java.io.FileNotFoundException if <code>source</code> isn't a normal file
* @throws IllegalArgumentException if <code>destinationDirectory</code> isn't a directory
* @throws IOException if <code>source</code> does not exist, the file in
* <code>destinationDirectory</code> cannot be written to, or an IO error
* occurs during copying.
* occurs during copying
*/
private static void copyFileToDirectoryIfModified( @Nonnull final File source,
@Nonnull final File destinationDirectory )
Expand All @@ -804,11 +803,11 @@ private static void copyFileToDirectoryIfModified( @Nonnull final File source,
* created if they don't already exist. <code>destination</code> will be overwritten if it
* already exists.
*
* @param source An existing non-directory <code>File</code> to copy bytes from.
* @param destination A non-directory <code>File</code> to write bytes to (possibly
* overwriting).
* @throws IOException if <code>source</code> does not exist, <code>destination</code> cannot be
* written to, or an IO error occurs during copying.
* @param source an existing non-directory <code>File</code> to copy bytes from
* @param destination a non-directory <code>File</code> to write bytes to (possibly
* overwriting)
* @throws IOException if <code>source</code> does not exist, <code>destination</code> cannot be
* written to, or an IO error occurs during copying.
* @throws java.io.FileNotFoundException if <code>destination</code> is a directory
*/
public static void copyFile( @Nonnull final File source, @Nonnull final File destination )
Expand Down

0 comments on commit 29e61f2

Please sign in to comment.