adding comments

Author: lemire

src/main/java/com/google/code/externalsorting/BinaryFileBuffer.java

@@ -9,22 +9,41 @@
  *
  */
 public final class BinaryFileBuffer implements IOStringStack {
+    /**
+     * Constructs a BinaryFileBuffer wrapping the given BufferedReader.
+     * @param r the BufferedReader to wrap
+     * @throws IOException if an I/O error occurs
+     */
     public BinaryFileBuffer(BufferedReader r) throws IOException {
         this.fbr = r;
         reload();
     }
+    /**
+     * Closes the underlying BufferedReader.
+     * @throws IOException if an I/O error occurs
+     */
     public void close() throws IOException {
         this.fbr.close();
     }
-
+    /**
+     * Checks if the buffer is empty.
+     * @return true if there are no more lines to read
+     */
     public boolean empty() {
         return this.cache == null;
     }
-
+    /**
+     * Returns the next line in the buffer without removing it.
+     * @return the next line as a String, or null if empty
+     */
     public String peek() {
         return this.cache;
     }
-
+    /**
+     * Removes and returns the next line in the buffer.
+     * @return the next line as a String
+     * @throws IOException if an I/O error occurs
+     */
     public String pop() throws IOException {
         String answer = peek().toString();// make a copy
         reload();

src/main/java/com/google/code/externalsorting/ExternalSort.java

@@ -1,6 +1,5 @@
 package com.google.code.externalsorting;
 
-// filename: ExternalSort.java
 import java.io.BufferedReader;
 import java.io.BufferedWriter;
 import java.io.EOFException;
@@ -48,100 +47,80 @@
  * http://lemire.me/blog/archives/2010/04/01/external-memory-sorting-in-java/
  */
 public class ExternalSort {
-
-
+        /**
+         * Default constructor for ExternalSort.
+         * No initialization required.
+         */
+        public ExternalSort() {
+        }
+        /**
+         * Affiche l'utilisation du programme sur la sortie standard.
+         */
         private static void displayUsage() {
-                System.out
-                        .println("java com.google.externalsorting.ExternalSort inputfile outputfile");
+                System.out.println("java com.google.externalsorting.ExternalSort inputfile outputfile");
                 System.out.println("Flags are:");
                 System.out.println("-v or --verbose: verbose output");
                 System.out.println("-d or --distinct: prune duplicate lines");
-                System.out
-                        .println("-t or --maxtmpfiles (followed by an integer): specify an upper bound on the number of temporary files");
-                System.out
-                        .println("-c or --charset (followed by a charset code): specify the character set to use (for sorting)");
-                System.out
-                        .println("-z or --gzip: use compression for the temporary files");
-                System.out
-                        .println("-H or --header (followed by an integer): ignore the first few lines");
-                System.out
-                        .println("-s or --store (following by a path): where to store the temporary files");
+                System.out.println("-t or --maxtmpfiles (followed by an integer): specify an upper bound on the number of temporary files");
+                System.out.println("-c or --charset (followed by a charset code): specify the character set to use (for sorting)");
+                System.out.println("-z or --gzip: use compression for the temporary files");
+                System.out.println("-H or --header (followed by an integer): ignore the first few lines");
+                System.out.println("-s or --store (following by a path): where to store the temporary files");
                 System.out.println("-h or --help: display this message");
         }
 
         /**
-         * This method calls the garbage collector and then returns the free
-         * memory. This avoids problems with applications where the GC hasn't
-         * reclaimed memory and reports no available memory.
-         *
-         * @return available memory
+         * Cette méthode appelle le garbage collector et retourne la mémoire libre.
+         * @return mémoire disponible en octets
          */
         public static long estimateAvailableMemory() {
-          System.gc();
-          // http://stackoverflow.com/questions/12807797/java-get-available-memory
-          Runtime r = Runtime.getRuntime();
-          long allocatedMemory = r.totalMemory() - r.freeMemory();
-          long presFreeMemory = r.maxMemory() - allocatedMemory;
-          return presFreeMemory;
+                System.gc();
+                Runtime r = Runtime.getRuntime();
+                long allocatedMemory = r.totalMemory() - r.freeMemory();
+                long presFreeMemory = r.maxMemory() - allocatedMemory;
+                return presFreeMemory;
         }
 
         /**
-         * we divide the file into small blocks. If the blocks are too small, we
-         * shall create too many temporary files. If they are too big, we shall
-         * be using too much memory.
-         *
-         * @param sizeoffile how much data (in bytes) can we expect
-         * @param maxtmpfiles how many temporary files can we create (e.g., 1024)
-         * @param maxMemory Maximum memory to use (in bytes)
-         * @return the estimate
+         * Calcule la taille optimale des blocs pour le tri externe.
+         * @param sizeoffile taille du fichier en octets
+         * @param maxtmpfiles nombre maximal de fichiers temporaires
+         * @param maxMemory mémoire maximale à utiliser
+         * @return estimation de la taille du bloc
          */
-        public static long estimateBestSizeOfBlocks(final long sizeoffile,
-                final int maxtmpfiles, final long maxMemory) {
-                // we don't want to open up much more than maxtmpfiles temporary
-                // files, better run
-                // out of memory first.
-                long blocksize = sizeoffile / maxtmpfiles
-                        + (sizeoffile % maxtmpfiles == 0 ? 0 : 1);
-
-                // on the other hand, we don't want to create many temporary
-                // files
-                // for naught. If blocksize is smaller than half the free
-                // memory, grow it.
+        public static long estimateBestSizeOfBlocks(final long sizeoffile, final int maxtmpfiles, final long maxMemory) {
+                long blocksize = sizeoffile / maxtmpfiles + (sizeoffile % maxtmpfiles == 0 ? 0 : 1);
                 if (blocksize < maxMemory / 2) {
                         blocksize = maxMemory / 2;
                 }
                 return blocksize;
         }
 
         /**
-         * @param args command line argument
-         * @throws IOException generic IO exception
+         * Main entry point for the external sorting program.
+         * @param args command line arguments
+         * @throws IOException if an I/O error occurs
          */
         public static void main(final String[] args) throws IOException {
-                boolean verbose = false;
-                boolean distinct = false;
-                int maxtmpfiles = DEFAULTMAXTEMPFILES;
-                Charset cs = Charset.defaultCharset();
-                String inputfile = null, outputfile = null;
-                File tempFileStore = null;
-                boolean usegzip = false;
-                boolean parallel = true;
-                int headersize = 0;
-                for (int param = 0; param < args.length; ++param) {
-                        if (args[param].equals("-v")
-                                || args[param].equals("--verbose")) {
-                                verbose = true;
-                        } else if ((args[param].equals("-h") || args[param]
-                                .equals("--help"))) {
-                                displayUsage();
-                                return;
-                        } else if ((args[param].equals("-d") || args[param]
-                                .equals("--distinct"))) {
-                                distinct = true;
-                        } else if ((args[param].equals("-t") || args[param]
-                                .equals("--maxtmpfiles"))
-                                && args.length > param + 1) {
-                                param++;
+        boolean verbose = false;
+        boolean distinct = false;
+        int maxtmpfiles = DEFAULTMAXTEMPFILES;
+        Charset cs = Charset.defaultCharset();
+        String inputfile = null, outputfile = null;
+        File tempFileStore = null;
+        boolean usegzip = false;
+        boolean parallel = true;
+        int headersize = 0;
+        for (int param = 0; param < args.length; ++param) {
+            if (args[param].equals("-v") || args[param].equals("--verbose")) {
+                verbose = true;
+            } else if ((args[param].equals("-h") || args[param].equals("--help"))) {
+                displayUsage();
+                return;
+            } else if ((args[param].equals("-d") || args[param].equals("--distinct"))) {
+                distinct = true;
+            } else if ((args[param].equals("-t") || args[param].equals("--maxtmpfiles")) && args.length > param + 1) {
+                param++;
                                 maxtmpfiles = Integer.parseInt(args[param]);
                                 if (maxtmpfiles < 0) {
                                         System.err

src/main/java/com/google/code/externalsorting/IOStringStack.java

@@ -7,12 +7,29 @@
  * so that users of the library can roll their own.
  */
 public interface IOStringStack {
+    /**
+     * Closes the underlying resource.
+     * @throws IOException if an I/O error occurs
+     */
     public void close() throws IOException;
 
+    /**
+     * Checks if the stack is empty.
+     * @return true if empty, false otherwise
+     */
     public boolean empty();
 
+    /**
+     * Returns the next element without removing it.
+     * @return the next element as a String
+     */
     public String peek();
 
+    /**
+     * Removes and returns the next element.
+     * @return the next element as a String
+     * @throws IOException if an I/O error occurs
+     */
     public String pop() throws IOException;
 
 }

src/main/java/com/google/code/externalsorting/csv/CSVRecordBuffer.java

@@ -6,6 +6,10 @@
 import org.apache.commons.csv.CSVParser;
 import org.apache.commons.csv.CSVRecord;
 
+/**
+ * Buffer wrapper for CSVRecord iteration and management.
+ * Handles reading and closing of CSVParser resources.
+ */
 public class CSVRecordBuffer {
 
 	private Iterator<CSVRecord> iterator;
@@ -14,25 +18,48 @@ public class CSVRecordBuffer {
 
 	private CSVRecord cache;
 
+	/**
+	 * Constructs a CSVRecordBuffer wrapping the given CSVParser.
+	 * @param parser the CSVParser to wrap
+	 * @throws IOException if an I/O error occurs
+	 * @throws ClassNotFoundException if a class cannot be found
+	 */
 	public CSVRecordBuffer(CSVParser parser) throws IOException, ClassNotFoundException {
 		this.iterator = parser.iterator();
 		this.parser = parser;
 		reload();
 	}
 
+	/**
+	 * Closes the underlying CSVParser.
+	 * @throws IOException if an I/O error occurs
+	 */
 	public void close() throws IOException {
 		this.parser.close();
 	}
 
+	/**
+	 * Checks if the buffer is empty.
+	 * @return true if there are no more records to read
+	 */
 	public boolean empty() {
 		return this.cache == null;
 	}
 
+	/**
+	 * Returns the next CSVRecord in the buffer without removing it.
+	 * @return the next CSVRecord, or null if empty
+	 */
 	public CSVRecord peek() {
 		return this.cache;
 	}
 
-	//
+	/**
+	 * Removes and returns the next CSVRecord in the buffer.
+	 * @return the next CSVRecord
+	 * @throws IOException if an I/O error occurs
+	 * @throws ClassNotFoundException if a class cannot be found
+	 */
 	public CSVRecord pop() throws IOException, ClassNotFoundException {
 		CSVRecord answer = peek();// make a copy
 		reload();