bug4210 Added JavaDoc to date and time input widgets

java/com.sap.sailing.gwt.ui/src/main/java/com/sap/sailing/gwt/common/client/datetime/AbstractInput.java

@@ -8,10 +8,20 @@ import com.google.gwt.user.client.ui.Composite;
 import com.google.gwt.user.client.ui.HasValue;
 import com.google.gwt.user.client.ui.IsWidget;
 
+/**
+ * Abstract implementation for classes wrapping date and/or time inputs providing a fallback widget if the respective
+ * native input type is not supported.
+ */
 abstract class AbstractInput extends Composite implements DateTimeInput {
 
     private HasValue<Date> delegate;
 
+    /**
+     * Creates a new {@link AbstractInput} instance passing method calls to the provided delegate.
+     * 
+     * @param delegate
+     *            the native or fallback input for the respective input type
+     */
     protected <T extends HasValue<Date> & IsWidget> AbstractInput(T delegate) {
         DateTimeInputResources.INSTANCE.css().ensureInjected();
         this.delegate = delegate;

java/com.sap.sailing.gwt.ui/src/main/java/com/sap/sailing/gwt/common/client/datetime/DateAndTimeInput.java

@@ -11,8 +11,18 @@ import com.google.gwt.event.shared.HandlerRegistration;
 import com.google.gwt.i18n.client.DateTimeFormat;
 import com.google.gwt.user.client.ui.FlowPanel;
 
+/**
+ * Extension of {@link AbstractInput} for date and time inputs, providing a native input field of type "datetime-local",
+ * if supported. Otherwise a panel containing a {@link DateInput} and a {@link TimeInput} is used as fallback widget.
+ */
 public class DateAndTimeInput extends AbstractInput {
 
+    /**
+     * Created a new {@link DateAndTimeInput} instance which the provided {@link Accuracy accuracy}.
+     * 
+     * @param accuracy
+     *            {@link Accuracy} for the new input
+     */
     public DateAndTimeInput(Accuracy accuracy) {
         super(DateTimeInputType.DATETIME_LOCAL.isSupported() ? NativeDateTimeInput.datetimeLocale(accuracy)
                 : new DateAndTimePanel(accuracy));
@@ -24,7 +34,7 @@ public class DateAndTimeInput extends AbstractInput {
 
         private final DateTimeFormat dateFormat, timeFormat, datetimeFormat;
 
-        public DateAndTimePanel(Accuracy accuracy) {
+        private DateAndTimePanel(Accuracy accuracy) {
             add(this.dateInput = new DateInput());
             add(this.timeInput = new TimeInput(accuracy));
             dateInput.addStyleName(DateTimeInputResources.INSTANCE.css().dateTimeInput());

java/com.sap.sailing.gwt.ui/src/main/java/com/sap/sailing/gwt/common/client/datetime/DateInput.java

@@ -4,8 +4,15 @@ import com.google.gwt.i18n.client.DateTimeFormat;
 import com.google.gwt.i18n.client.DateTimeFormat.PredefinedFormat;
 import com.google.gwt.user.datepicker.client.DateBox;
 
+/**
+ * Extension of {@link AbstractInput} for date inputs, providing a native input field of type "date", if supported.
+ * Otherwise a {@link DateBox} with {@link PredefinedFormat#DATE_MEDIUM medium date format} is used as fallback widget.
+ */
 public class DateInput extends AbstractInput {
 
+    /**
+     * Created a new {@link DateInput} instance.
+     */
     public DateInput() {
         super(DateTimeInputType.TIME.isSupported() ? NativeDateTimeInput.date() : new CustomDateBox());
     }

java/com.sap.sailing.gwt.ui/src/main/java/com/sap/sailing/gwt/common/client/datetime/DateTimeInput.java

@@ -7,15 +7,24 @@ import com.google.gwt.i18n.client.DateTimeFormat;
 import com.google.gwt.user.client.ui.HasValue;
 import com.google.gwt.user.client.ui.IsWidget;
 
+/**
+ * Interface for date and/or time related input widgets holding a {@link Date date} value.
+ * 
+ * @see com.google.gwt.user.client.ui.IsWidget
+ * @see com.google.gwt.user.client.ui.HasValue
+ */
 public interface DateTimeInput extends IsWidget, HasValue<Date> {
 
+    /**
+     * Enumeration describing the accuracy of an input field of type "datetime-local" or "time".
+     */
     public enum Accuracy {
         MINUTES(60, "yyyy-MM-dd'T'HH:mm", "HH:mm"), SECONDS(1, "yyyy-MM-dd'T'HH:mm:ss", "HH:mm:ss");
 
         private static final DateTimeFormat DATE_FORMAT = DateTimeFormat.getFormat("yyyy-MM-dd");
 
-        private final String step;
         private final DateTimeFormat datetimeFormat, timeFormat;
+        private final String step;
 
         private Accuracy(int step, String datetimeFormat, String timeFormat) {
             this.step = String.valueOf(step);
@@ -23,20 +32,32 @@ public interface DateTimeInput extends IsWidget, HasValue<Date> {
             this.timeFormat = DateTimeFormat.getFormat(timeFormat);
         }
 
+        /**
+         * @return the {@link DateTimeFormat} for date inputs (always the same)
+         */
         public static DateTimeFormat getDateFormat() {
             return DATE_FORMAT;
         }
 
-        public String getStep() {
-            return step;
+        /**
+         * @return the {@link DateTimeFormat} for time inputs
+         */
+        public DateTimeFormat getTimeFormat() {
+            return timeFormat;
         }
 
+        /**
+         * @return the {@link DateTimeFormat} for date and time inputs
+         */
         public DateTimeFormat getDatetimeFormat() {
             return datetimeFormat;
         }
 
-        public DateTimeFormat getTimeFormat() {
-            return timeFormat;
+        /**
+         * @return the "step" attribute value to set on input fields of type "datetime-local" or "time"
+         */
+        public String getStep() {
+            return step;
         }
     }
 

java/com.sap.sailing.gwt.ui/src/main/java/com/sap/sailing/gwt/common/client/datetime/DateTimeInputType.java

@@ -2,7 +2,7 @@ package com.sap.sailing.gwt.common.client.datetime;
 
 /**
  * Enumeration of date and/or time related input {@link #getType() types} whose {@link #isSupported() support} in the
- * currently used browser was checked at runtime.
+ * currently used browser will be checked at runtime.
  */
 public enum DateTimeInputType {
     

java/com.sap.sailing.gwt.ui/src/main/java/com/sap/sailing/gwt/common/client/datetime/NativeDateTimeInput.java

@@ -12,18 +12,43 @@ import com.google.gwt.i18n.client.DateTimeFormat;
 import com.google.gwt.user.client.Event;
 import com.google.gwt.user.client.ui.Widget;
 
+/**
+ * Factory class to create native input field of type "{@link #datetimeLocale(Accuracy) datetime-local}",
+ * "{@link #date() date}" or "{@link #time(Accuracy) time}".
+ */
 class NativeDateTimeInput extends Widget implements DateTimeInput {
 
     private static final String ATTR_TYPE = "type", ATTR_STEP = "step";
 
+    /**
+     * Creates a native input field of type "date".
+     * 
+     * @return the newly created instance as {@link DateTimeInput} abstraction
+     */
     static DateTimeInput date() {
         return new NativeDateTimeInput(DateTimeInputType.DATE, "", Accuracy.getDateFormat());
     }
 
+    /**
+     * Creates a native input field of type "time" which the provided {@link Accuracy accuracy}.
+     * 
+     * @param accuracy
+     *            {@link Accuracy} for the new native input field
+     * 
+     * @return the newly created instance as {@link DateTimeInput} abstraction
+     */
     static DateTimeInput time(Accuracy accuracy) {
         return new NativeDateTimeInput(DateTimeInputType.TIME, accuracy.getStep(), accuracy.getTimeFormat());
     }
 
+    /**
+     * Creates a native input field of type "datetime-local" which the provided {@link Accuracy accuracy}.
+     * 
+     * @param accuracy
+     *            {@link Accuracy} for the new native input field
+     * 
+     * @return the newly created instance as {@link DateTimeInput} abstraction
+     */
     static DateTimeInput datetimeLocale(Accuracy accuracy) {
         return new NativeDateTimeInput(DateTimeInputType.DATETIME_LOCAL, accuracy.getStep(),
                 accuracy.getDatetimeFormat());

java/com.sap.sailing.gwt.ui/src/main/java/com/sap/sailing/gwt/common/client/datetime/TimeInput.java

@@ -11,8 +11,19 @@ import com.google.gwt.text.shared.AbstractRenderer;
 import com.google.gwt.text.shared.Parser;
 import com.google.gwt.user.client.ui.ValueBox;
 
+/**
+ * Extension of {@link AbstractInput} for time inputs, providing a native input field of type "time", if supported.
+ * Otherwise a {@link ValueBox} for {@link Date dates} is used as fallback widget using a
+ * {@link PredefinedFormat#TIME_SHORT short} or a {@link PredefinedFormat#TIME_MEDIUM medium} time format.
+ */
 public class TimeInput extends AbstractInput {
 
+    /**
+     * Created a new {@link TimeInput} instance which the provided {@link Accuracy accuracy}.
+     * 
+     * @param accuracy
+     *            {@link Accuracy} for the new input
+     */
     public TimeInput(Accuracy accuracy) {
         super(DateTimeInputType.TIME.isSupported() ? NativeDateTimeInput.time(accuracy)
                 : new TimeBox(new TimeConverter(accuracy)));