Index: src/main/java/java/util/logging/FileHandler.java
===================================================================
--- src/main/java/java/util/logging/FileHandler.java (revision 537769)
+++ src/main/java/java/util/logging/FileHandler.java (working copy)
@@ -32,74 +32,75 @@
import org.apache.harmony.logging.internal.nls.Messages;
/**
- * A Handler writes description of logging event into a specified
- * file or a rotating set of files.
+ * A FileHandler is a Handler that writes logging events to one
+ * or more files.
+ *
*
- * If a set of files are used, when a given amount of data has been written to - * one file, this file is closed, and another file is opened. The name of these - * files are generated by given name pattern, see below for details. + * If multiple files are used, when a given amount of data has been written to + * one file, this file is closed, and the next file is opened. The names of + * these files are generated by the given name pattern, see below for details. + * When all the files have all been filled the Handler returns to the first one + * and goes through the set again. *
- *- * By default the IO buffering mechanism is enabled, but when each log record is - * complete, it is flushed out. - *
+ * *
- * XMLFormatter is default formatter for FileHandler.
- *
- * MemoryHandler will read following LogManager
- * properties for initialization, if given properties are not defined or has
- * invalid values, default value will be used.
+ * FileHandler defines the following configuration properties,
+ * which are read by the LogManager on initialization. If the
+ * properties have not been specified then defaults will be used. The properties
+ * and defaults are as follows:
*
Handler, defaults to Level.ALL.Filter
- * class name, defaults to no Filter.Formatter class, defaults to
+ * FileHandler appends to a file's existing content, if false it
+ * overwrites it. Default is false.Filter class. No Filter is used by default.Formatter class. Default is
* java.util.logging.XMLFormatter.FileHandler should append onto existing files, defaults to
- * false.Handler. Default is Level.ALL.- * Name pattern is a string that may includes some special sub-strings, which - * will be replaced to generate output files: + * The name pattern is a String that can contain some of the following + * sub-strings, which will be replaced to generate the output file names: *
+ * The generation numbers, denoted by "%g" in the filename pattern will be + * created in ascending numerical order from 0, i.e. 0,1,2,3... If "%g" was not + * present in the pattern and more than one file is being used then a dot and a + * generation number is appended to the filename at the end. This is equivalent + * to appending ".%g" to the pattern. *
+ * *
- * The "%u" unique field is used to avoid conflicts and set to 0 at first. If
- * one FileHandler tries to open the filename which is currently
- * in use by another process, it will repeatedly increment the unique number
- * field and try again. If the "%u" component has not been included in the file
- * name pattern and some contention on a file does occur then a unique numerical
- * value will be added to the end of the filename in question immediately to the
- * right of a dot. The unique IDs for avoiding conflicts is only guaranteed to
- * work reliably when using a local disk file system.
+ * The unique identifier, denoted by "%u" in the filename pattern will always be
+ * 0 unless the FileHandler is unable to open the file. In that
+ * case 1 is tried, then 2, and so on until a file is found that can be opened.
+ * If "%u" was not present in the pattern but a unique number is required then a
+ * dot and a unique number is added to the end of the filename, equivalent to
+ * appending ".%u" to the pattern.
*