[issue #261] Document requirement for subsequent media scan

src/me/guillaumin/android/osmtracker/util/FileSystemUtils.java

@@ -8,6 +8,7 @@
 import java.util.ArrayList;
 import java.util.List;
 
+import android.media.MediaScannerConnection;
 import android.util.Log;
 
 public final class FileSystemUtils {
@@ -20,7 +21,14 @@ public final class FileSystemUtils {
 	private static final int DELETE_MAX_RECURSION_DEPTH = 1;
 
 	/**
-	 * Copy copy file sourceFile to the directory destination directory
+	 * @brief Copies file sourceFile to the directory destination directory.
+	 * 
+	 * After this method returns, the caller should trigger a media scan to ensure the copied files
+	 * are known to the media scanner and visible over MTP. This can be done by broadcasting an
+	 * {@code Intent.ACTION_MEDIA_SCANNER_SCAN_FILE} with the URI of the new file, or by calling
+	 * {@code MediaScannerConnection.scanFile(file, null)}, passing the full path to the newly added
+	 * file as the {@code file} argument.
+	 * 
 	 * @param destinationDirectory location where the file to be copied
 	 * @param sourceFile the location of the file to copy
 	 * @param targetFileName name of the target file
@@ -65,7 +73,13 @@ public static boolean copyFile(final File destinationDirectory, final File sourc
 	}
 
 	/**
-	 * copies all files within a directory to another directory
+	 * @brief Copies all files within a directory to another directory
+	 * 
+	 * After this method returns, the caller should trigger a media scan to ensure the copied files
+	 * are known to the media scanner and visible over MTP. This can be done by calling
+	 * {@code MediaScannerConnection.scanFile(context, files, null, null)}, passing an array of the
+	 * newly added files as the {@code files} argument.
+	 * 
 	 * @param destinationDirectory the target directory
 	 * @param sourceDirectory the source directory 
 	 * @return true if all contents were copied successfully, false otherwise