From 48772f9b17b35e27976b89c8c452af652caaa6d0 Mon Sep 17 00:00:00 2001 From: jjobes Date: Tue, 3 Feb 2015 13:30:30 -0500 Subject: [PATCH] improved javadoc comments --- .../slidedatetimepicker/CustomDatePicker.java | 8 +- .../slidedatetimepicker/CustomTimePicker.java | 8 +- .../slidedatetimepicker/CustomViewPager.java | 6 +- .../slidedatetimepicker/DateFragment.java | 11 +- .../SlideDateTimeDialogFragment.java | 45 ++++--- .../SlideDateTimeListener.java | 14 +-- .../SlideDateTimePicker.java | 112 ++++++++++++++---- .../slidedatetimepicker/TimeFragment.java | 5 +- 8 files changed, 150 insertions(+), 59 deletions(-) diff --git a/SlideDateTimePicker/src/com/github/jjobes/slidedatetimepicker/CustomDatePicker.java b/SlideDateTimePicker/src/com/github/jjobes/slidedatetimepicker/CustomDatePicker.java index fac4bc4..d419445 100644 --- a/SlideDateTimePicker/src/com/github/jjobes/slidedatetimepicker/CustomDatePicker.java +++ b/SlideDateTimePicker/src/com/github/jjobes/slidedatetimepicker/CustomDatePicker.java @@ -5,16 +5,18 @@ import android.content.Context; import android.util.AttributeSet; import android.util.Log; +import android.widget.DatePicker; import android.widget.NumberPicker; /** - * A subclass of DatePicker that uses reflection to allow - * for customization of the default blue dividers. + * A subclass of {@link android.widget.DatePicker} that uses + * reflection to allow for customization of the default blue + * dividers. * * @author jjobes * */ -public class CustomDatePicker extends android.widget.DatePicker +public class CustomDatePicker extends DatePicker { private static final String TAG = "CustomDatePicker"; diff --git a/SlideDateTimePicker/src/com/github/jjobes/slidedatetimepicker/CustomTimePicker.java b/SlideDateTimePicker/src/com/github/jjobes/slidedatetimepicker/CustomTimePicker.java index faeccf9..eb361b2 100644 --- a/SlideDateTimePicker/src/com/github/jjobes/slidedatetimepicker/CustomTimePicker.java +++ b/SlideDateTimePicker/src/com/github/jjobes/slidedatetimepicker/CustomTimePicker.java @@ -6,15 +6,17 @@ import android.util.AttributeSet; import android.util.Log; import android.widget.NumberPicker; +import android.widget.TimePicker; /** - * This is a subclass of TimePicker that uses reflection to allow - * for customization of the default blue dividers. + * A subclass of {@link android.widget.TimePicker} that uses + * reflection to allow for customization of the default blue + * dividers. * * @author jjobes * */ -public class CustomTimePicker extends android.widget.TimePicker +public class CustomTimePicker extends TimePicker { private static final String TAG = "CustomTimePicker"; diff --git a/SlideDateTimePicker/src/com/github/jjobes/slidedatetimepicker/CustomViewPager.java b/SlideDateTimePicker/src/com/github/jjobes/slidedatetimepicker/CustomViewPager.java index d1e3df7..93166fc 100644 --- a/SlideDateTimePicker/src/com/github/jjobes/slidedatetimepicker/CustomViewPager.java +++ b/SlideDateTimePicker/src/com/github/jjobes/slidedatetimepicker/CustomViewPager.java @@ -10,9 +10,9 @@ import android.widget.TimePicker; /** - * A custom ViewPager implementation that corrects the height of the ViewPager - * and also dispatches touch events to either the ViewPager or the date or time - * picker depending on the direction of the swipe. + * A custom {@link android.support.v4.view.ViewPager} implementation that corrects + * the height of the ViewPager and also dispatches touch events to either the ViewPager + * or the date or time picker depending on the direction of the swipe. * * @author jjobes * diff --git a/SlideDateTimePicker/src/com/github/jjobes/slidedatetimepicker/DateFragment.java b/SlideDateTimePicker/src/com/github/jjobes/slidedatetimepicker/DateFragment.java index 8eb2c62..a27140b 100644 --- a/SlideDateTimePicker/src/com/github/jjobes/slidedatetimepicker/DateFragment.java +++ b/SlideDateTimePicker/src/com/github/jjobes/slidedatetimepicker/DateFragment.java @@ -14,7 +14,7 @@ /** * The fragment for the first page in the ViewPager that holds - * the DatePicker. + * the {@link CustomDatePicker}. * * @author jjobes * @@ -32,7 +32,7 @@ public interface DateChangedListener } private DateChangedListener mCallback; - private DatePicker mDatePicker; + private CustomDatePicker mDatePicker; public DateFragment() { @@ -40,7 +40,8 @@ public DateFragment() } /** - * Cast the reference to SlideDateTimeDialogFragment to a DateChangedListener. + * Cast the reference to {@link SlideDateTimeDialogFragment} + * to a {@link DateChangedListener}. */ @Override public void onCreate(Bundle savedInstanceState) @@ -61,7 +62,7 @@ public void onCreate(Bundle savedInstanceState) /** * Return an instance of DateFragment with its bundle filled with the * constructor arguments. The values in the bundle are retrieved in - * onCreateView() below to properly initialize the DatePicker. + * {@link #onCreateView()} below to properly initialize the DatePicker. * * @param theme * @param year @@ -118,7 +119,7 @@ public View onCreateView(LayoutInflater inflater, ViewGroup container, View v = localInflater.inflate(R.layout.fragment_date, container, false); - mDatePicker = (DatePicker) v.findViewById(R.id.datePicker); + mDatePicker = (CustomDatePicker) v.findViewById(R.id.datePicker); // block keyboard popping up on touch mDatePicker.setDescendantFocusability(DatePicker.FOCUS_BLOCK_DESCENDANTS); mDatePicker.init( diff --git a/SlideDateTimePicker/src/com/github/jjobes/slidedatetimepicker/SlideDateTimeDialogFragment.java b/SlideDateTimePicker/src/com/github/jjobes/slidedatetimepicker/SlideDateTimeDialogFragment.java index 08f0d2a..23a6f0c 100644 --- a/SlideDateTimePicker/src/com/github/jjobes/slidedatetimepicker/SlideDateTimeDialogFragment.java +++ b/SlideDateTimePicker/src/com/github/jjobes/slidedatetimepicker/SlideDateTimeDialogFragment.java @@ -22,9 +22,12 @@ import android.widget.Button; /** - * The DialogFragment that contains the SlidingTabLayout and CustomViewPager. - * The CustomViewPager contains the DateFragment and TimeFragment. - * This DialogFragment is managed by SlideDateTimePicker. + *

The {@code DialogFragment} that contains the {@link SlidingTabLayout} + * and {@link CustomViewPager}.

+ * + *

The {@code CustomViewPager} contains the {@link DateFragment} and {@link TimeFragment}.

+ * + *

This {@code DialogFragment} is managed by {@link SlideDateTimePicker}.

* * @author jjobes * @@ -63,8 +66,10 @@ public SlideDateTimeDialogFragment() } /** - * Return a new instance of SlideDateTimeDialogFragment with its bundle - * filled with the initial date/time. + *

Return a new instance of {@code SlideDateTimeDialogFragment} with its bundle + * filled with the incoming arguments.

+ * + *

Called by {@link SlideDateTimePicker#show()}.

* * @param listener * @param initialDate @@ -268,10 +273,13 @@ public void onClick(View v) } /** - * The callback used by the DatePicker to update mCalendar as the user - * changes the date. Each time this is called, we also update the text - * on the date tab to reflect the date the user has currenly selected. - * Implements the DateFragment.DateChangedListener interface. + *

The callback used by the DatePicker to update {@code mCalendar} as + * the user changes the date. Each time this is called, we also update + * the text on the date tab to reflect the date the user has currenly + * selected.

+ * + *

Implements the {@link DateFragment.DateChangedListener} + * interface.

*/ @Override public void onDateChanged(int year, int month, int day) @@ -282,10 +290,13 @@ public void onDateChanged(int year, int month, int day) } /** - * The callback used by the TimePicker to update mCalendar as the user - * changes the time. Each time this is called, we also update the text - * on the time tab to reflect the time the user has currenly selected. - * Implements the TimeFragment.TimeChangedListener interface. + *

The callback used by the TimePicker to update {@code mCalendar} as + * the user changes the time. Each time this is called, we also update + * the text on the time tab to reflect the time the user has currenly + * selected.

+ * + *

Implements the {@link TimeFragment.TimeChangedListener} + * interface.

*/ @Override public void onTimeChanged(int hour, int minute) @@ -328,9 +339,11 @@ private void updateTimeTab() } /** - * Called when the user clicks outside the dialog or presses the Back - * button. Actual Cancel button clicks are handled by mCancelButton's - * event handler. + *

Called when the user clicks outside the dialog or presses the Back + * button.

+ * + *

Note: Actual Cancel button clicks are handled by {@code mCancelButton}'s + * event handler.

*/ @Override public void onCancel(DialogInterface dialog) diff --git a/SlideDateTimePicker/src/com/github/jjobes/slidedatetimepicker/SlideDateTimeListener.java b/SlideDateTimePicker/src/com/github/jjobes/slidedatetimepicker/SlideDateTimeListener.java index 748be11..d9d675c 100644 --- a/SlideDateTimePicker/src/com/github/jjobes/slidedatetimepicker/SlideDateTimeListener.java +++ b/SlideDateTimePicker/src/com/github/jjobes/slidedatetimepicker/SlideDateTimeListener.java @@ -3,13 +3,13 @@ import java.util.Date; /** - * This listener class informs the client when the user sets - * a date and time by pressing "OK" or cancels the dialog. + *

This listener class informs the client when the user sets + * a date and time by pressing "OK", or cancels the dialog.

* - * Overriding onDateTimeCancel() is optional. The client can - * always override this to listen for when the user cancels - * the dialog. This is called when the user presses the Cancel - * button, touches outside the dialog or presses the Back button. + *

Overriding {@code onDateTimeCancel()} is optional. The client + * can override this to listen for when the user cancels the dialog. + * This is called when the user presses the dialog's Cancel button, + * touches outside the dialog or presses the device's Back button.

* * @author jjobes * @@ -20,7 +20,7 @@ public abstract class SlideDateTimeListener * Informs the client when the user presses "OK" * and selects a date and time. * - * @param date The Date object that contains the date + * @param date The {@code Date} object that contains the date * and time that the user has selected. */ public abstract void onDateTimeSet(Date date); diff --git a/SlideDateTimePicker/src/com/github/jjobes/slidedatetimepicker/SlideDateTimePicker.java b/SlideDateTimePicker/src/com/github/jjobes/slidedatetimepicker/SlideDateTimePicker.java index 18d78e9..ce3afa6 100644 --- a/SlideDateTimePicker/src/com/github/jjobes/slidedatetimepicker/SlideDateTimePicker.java +++ b/SlideDateTimePicker/src/com/github/jjobes/slidedatetimepicker/SlideDateTimePicker.java @@ -7,7 +7,11 @@ import android.support.v4.app.FragmentTransaction; /** - * Interface for the client to create a new SlideDateTimePicker. + *

This class contains methods for the library client to create + * a new {@code SlideDateTimePicker}.

+ * + *

It also implements a Builder API that offers more convenient + * object creation.

* * @author jjobes * @@ -28,10 +32,10 @@ public class SlideDateTimePicker private int mIndicatorColor; /** - * Creates a new instance of SlideDateTimePicker. + * Creates a new instance of {@code SlideDateTimePicker}. * - * @param fm The FragmentManager from the calling activity that is used - * internally to show the DialogFragment. + * @param fm The {@code FragmentManager} from the calling activity that is used + * internally to show the {@code DialogFragment}. */ public SlideDateTimePicker(FragmentManager fm) { @@ -50,9 +54,10 @@ public SlideDateTimePicker(FragmentManager fm) } /** - * Sets the listener that is used to inform the client when - * the user selects a new date and time. This must be called - * before show(). + *

Sets the listener that is used to inform the client when + * the user selects a new date and time.

+ * + *

This must be called before {@link #show()}.

* * @param listener */ @@ -62,11 +67,13 @@ public void setListener(SlideDateTimeListener listener) } /** - * Sets the initial date and time to display in the date - * and time pickers. If this method is not called, the - * current date and time will be displayed. + *

Sets the initial date and time to display in the date + * and time pickers.

+ * + *

If this method is not called, the current date and time + * will be displayed.

* - * @param initialDate the date object used to determine the + * @param initialDate the {@code Date} object used to determine the * initial date and time to display */ public void setInitialDate(Date initialDate) @@ -75,8 +82,9 @@ public void setInitialDate(Date initialDate) } /** - * Sets the minimum date that the DatePicker should show. - * Should be called before show(). + *

Sets the minimum date that the DatePicker should show.

+ * + *

This must be called before {@link #show()}.

* * @param minDate the minimum selectable date for the DatePicker */ @@ -86,8 +94,9 @@ public void setMinDate(Date minDate) } /** - * Sets the maximum date that the DatePicker should show. - * Should be called before show(). + *

Sets the maximum date that the DatePicker should show.

+ * + *

This must be called before {@link #show()}.

* * @param maxDate the maximum selectable date for the DatePicker */ @@ -121,8 +130,8 @@ public void setIs24HourTime(boolean is24HourTime) * Sets the theme of the dialog. If no theme is specified, it * defaults to holo light. * - * @param theme SlideDateTimePicker.HOLO_DARK for a dark theme, or - * SlideDateTimePicker.HOLO_LIGHT for a light theme + * @param theme {@code SlideDateTimePicker.HOLO_DARK} for a dark theme, or + * {@code SlideDateTimePicker.HOLO_LIGHT} for a light theme */ public void setTheme(int theme) { @@ -140,8 +149,8 @@ public void setIndicatorColor(int indicatorColor) } /** - * Shows the SlideDateTimeDialogFragment dialog. Make sure to - * call setListener() before calling this. + * Shows the dialog to the user. Make sure to call + * {@link #setListener()} before calling this. */ public void show() { @@ -172,7 +181,8 @@ public void show() } /* - * The following implements the builder API. + * The following implements the builder API to simplify + * creation and display of the dialog. */ public static class Builder { @@ -194,30 +204,72 @@ public Builder(FragmentManager fm) this.fm = fm; } + /** + *

Sets the listener that is used to inform the client when + * the user selects a new date and time.

+ * + *

This must be called before {@link #show()}.

+ * + * @param listener + */ public Builder listener(SlideDateTimeListener listener) { this.listener = listener; return this; } + /** + *

Sets the initial date and time to display in the date + * and time pickers.

+ * + *

If this method is not called, the current date and time + * will be displayed.

+ * + * @param initialDate the {@code Date} object used to determine the + * initial date and time to display + */ public Builder initialDate(Date initialDate) { this.initialDate = initialDate; return this; } + /** + *

Sets the minimum date that the DatePicker should show.

+ * + *

This must be called before {@link #show()}.

+ * + * @param minDate the minimum selectable date for the DatePicker + */ public Builder minDate(Date minDate) { this.minDate = minDate; return this; } + /** + *

Sets the maximum date that the DatePicker should show.

+ * + *

This must be called before {@link #show()}.

+ * + * @param maxDate the maximum selectable date for the DatePicker + */ public Builder maxDate(Date maxDate) { this.maxDate = maxDate; return this; } + /** + * Sets whether the TimePicker is in 12 hour (AM/PM) or 24 hour + * mode. If this method is not called, the device's default + * time format is used. This effects both the time displayed + * in the tab and the TimePicker. Should be called before show(). + * + * @param is24HourTime true to force 24 hour time format, + * false to force 12 hour (AM/PM) time + * format. + */ public Builder is24HourTime(boolean is24HourTime) { this.isClientSpecified24HourTime = true; @@ -225,18 +277,38 @@ public Builder is24HourTime(boolean is24HourTime) return this; } + /** + * Sets the theme of the dialog. If no theme is specified, it + * defaults to holo light. + * + * @param theme {@code SlideDateTimePicker.HOLO_DARK} for a dark theme, or + * {@code SlideDateTimePicker.HOLO_LIGHT} for a light theme + */ public Builder theme(int theme) { this.theme = theme; return this; } + /** + * Sets the color of the underline for the currently selected tab. + * + * @param indicatorColor the color of the selected tab's underline + */ public Builder indicatorColor(int indicatorColor) { this.indicatorColor = indicatorColor; return this; } + /** + *

Build and return a {@code SlideDateTimePicker} object based on the previously + * supplied parameters.

+ * + *

You should call {@link #show()} immediately after this.

+ * + * @return + */ public SlideDateTimePicker build() { SlideDateTimePicker picker = new SlideDateTimePicker(fm); diff --git a/SlideDateTimePicker/src/com/github/jjobes/slidedatetimepicker/TimeFragment.java b/SlideDateTimePicker/src/com/github/jjobes/slidedatetimepicker/TimeFragment.java index 3bb3cf5..89a38a2 100644 --- a/SlideDateTimePicker/src/com/github/jjobes/slidedatetimepicker/TimeFragment.java +++ b/SlideDateTimePicker/src/com/github/jjobes/slidedatetimepicker/TimeFragment.java @@ -42,7 +42,8 @@ public TimeFragment() } /** - * Cast the reference to SlideDateTimeDialogFragment to a TimeChangedListener. + * Cast the reference to {@link SlideDateTimeDialogFragment} to a + * {@link TimeChangedListener}. */ @Override public void onCreate(Bundle savedInstanceState) @@ -63,7 +64,7 @@ public void onCreate(Bundle savedInstanceState) /** * Return an instance of TimeFragment with its bundle filled with the * constructor arguments. The values in the bundle are retrieved in - * onCreateView() below to properly initialize the TimePicker. + * {@link #onCreateView()} below to properly initialize the TimePicker. * * @param theme * @param hour