- Added Javadoc for the class and two methods explaining issue with dates

prior to 1.1.1970.


git-svn-id: https://svn.apache.org/repos/asf/lucene/java/trunk@149774 13f79535-47bb-0310-9956-ffa450edef68

src/java/org/apache/lucene/document/DateField.java

@@ -56,9 +56,14 @@ package org.apache.lucene.document;
 
 import java.util.Date;
 
-/** Provides support for converting dates to strings and vice-versa.  The
-   * strings are structured so that lexicographic sorting orders by date.  This
-   * makes them suitable for use as field values and search terms.  */
+/**
+ * Provides support for converting dates to strings and vice-versa.
+ * The strings are structured so that lexicographic sorting orders by date.
+ * This makes them suitable for use as field values and search terms.
+ * <P>
+ * Note: currenly dates before 1970 cannot be used, and therefore cannot be
+ * indexed.
+ */
 public class DateField {
   private DateField() {}
 
@@ -77,12 +82,20 @@ public class DateField {
       buffer[i] = c;
     return new String(buffer);
   }
-  
-  /** Converts a Date to a string suitable for indexing. */
+
+  /**
+   * Converts a Date to a string suitable for indexing.
+   * This method will throw a RuntimeException if the date specified in the
+   * method argument is before 1970.
+   */
   public static String dateToString(Date date) {
     return timeToString(date.getTime());
   }
-  /** Converts a millisecond time to a string suitable for indexing. */
+  /**
+   * Converts a millisecond time to a string suitable for indexing.
+   * This method will throw a RuntimeException if the time specified in the
+   * method argument is negative, that is, before 1970.
+   */
   public static String timeToString(long time) {
     if (time < 0)
       throw new RuntimeException("time too early");