Improve sunrise/set method names (#254)

* Migrate AstronomicalCalendar to use LocalDate - Fix Timezone Bug - Use correct SUNRISE enum in getInstantFromTime

* Fix Javadocs

* Rename getSunrise to getSunriseWithElevation.
Fix javadoc on `isUseElevation`

* Rename getElevationAdjustedSunset/rise to avoid further confusion.

Author: dickermoshe

src/main/java/com/kosherjava/zmanim/AstronomicalCalendar.java

@@ -23,15 +23,13 @@
 import java.time.LocalTime;
 import java.time.ZoneOffset;
 import java.time.ZonedDateTime;
-import java.time.temporal.ChronoUnit;
-import java.util.TimeZone;
 
 import com.kosherjava.zmanim.util.AstronomicalCalculator;
 import com.kosherjava.zmanim.util.GeoLocation;
 import com.kosherjava.zmanim.util.ZmanimFormatter;
 
 /**
- * A Java calendar that calculates astronomical times such as {@link #getSunrise() sunrise}, {@link #getSunset()
+ * A Java calendar that calculates astronomical times such as {@link #getSunriseWithElevation() sunrise}, {@link #getSunsetWithElevation()
  * sunset} and twilight times. This class contains a {@link #getLocalDate() zonedDateTime} and can therefore use the standard
  * Calendar functionality to change dates etc. The calculation engine used to calculate the astronomical times can be
  * changed to a different implementation by implementing the abstract {@link AstronomicalCalculator} and setting it with
@@ -112,7 +110,7 @@ public class AstronomicalCalendar implements Cloneable {
 	private AstronomicalCalculator astronomicalCalculator;
 
 	/**
-	 * The getSunrise method returns a <code>Instant</code> representing the
+	 * The getSunriseWithElevation method returns a <code>Instant</code> representing the
 	 * {@link AstronomicalCalculator#getElevationAdjustment(double) elevation adjusted} sunrise time. The zenith used
 	 * for the calculation uses {@link #GEOMETRIC_ZENITH geometric zenith} of 90&deg; plus
 	 * {@link AstronomicalCalculator#getElevationAdjustment(double)}. This is adjusted by the
@@ -127,14 +125,36 @@ public class AstronomicalCalendar implements Cloneable {
 	 * @see #getSeaLevelSunrise()
 	 * @see AstronomicalCalendar#getUTCSunrise
 	 */
-	public Instant getSunrise() {
+	public Instant getSunriseWithElevation() {
 		double sunrise = getUTCSunrise(GEOMETRIC_ZENITH);
 		if (Double.isNaN(sunrise)) {
 			return null;
 		} else {
 			return getInstantFromTime(sunrise, SolarEvent.SUNRISE);
 		}
 	}
+    /**
+     * @deprecated Use {@link #getSunriseWithElevation()} instead.
+     * This method already accounts for the observer's elevation, but the name
+     * does not clearly indicate this behavior. The replacement method has a
+     * clearer and more descriptive name.
+     *
+     * @return the <code>Instant</code> representing the exact sunrise time. If the calculation can't be computed such as
+     *         in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it
+     *         does not set, a <code>null</code> will be returned. See detailed explanation on top of the page.
+     * @see AstronomicalCalculator#adjustZenith
+     * @see #getSeaLevelSunrise()
+     * @see AstronomicalCalendar#getUTCSunrise
+     */
+    @Deprecated(forRemoval = false)
+    public Instant getSunrise() {
+        double sunrise = getUTCSunrise(GEOMETRIC_ZENITH);
+        if (Double.isNaN(sunrise)) {
+            return null;
+        } else {
+            return getInstantFromTime(sunrise, SolarEvent.SUNRISE);
+        }
+    }
 
 	/**
 	 * A method that returns the sunrise without {@link AstronomicalCalculator#getElevationAdjustment(double) elevation
@@ -145,7 +165,7 @@ public Instant getSunrise() {
 	 * @return the <code>Instant</code> representing the exact sea-level sunrise time. If the calculation can't be computed
 	 *         such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one
 	 *         where it does not set, a <code>null</code> will be returned. See detailed explanation on top of the page.
-	 * @see AstronomicalCalendar#getSunrise
+	 * @see AstronomicalCalendar#getSunriseWithElevation
 	 * @see AstronomicalCalendar#getUTCSeaLevelSunrise
 	 * @see #getSeaLevelSunset()
 	 */
@@ -196,25 +216,48 @@ public Instant getBeginAstronomicalTwilight() {
 		return getSunriseOffsetByDegrees(ASTRONOMICAL_ZENITH);
 	}
 
+    /**
+     * The getSunsetWithElevation method returns a <code>Instant</code> representing the
+     * {@link AstronomicalCalculator#getElevationAdjustment(double) elevation adjusted} sunset time. The zenith used for
+     * the calculation uses {@link #GEOMETRIC_ZENITH geometric zenith} of 90&deg; plus
+     * {@link AstronomicalCalculator#getElevationAdjustment(double)}. This is adjusted by the
+     * {@link AstronomicalCalculator} to add approximately 50/60 of a degree to account for 34 archminutes of refraction
+     * and 16 archminutes for the sun's radius for a total of {@link AstronomicalCalculator#adjustZenith 90.83333&deg;}.
+     * See documentation for the specific implementation of the {@link AstronomicalCalculator} that you are using. Note:
+     * In certain cases the calculates sunset will occur before sunrise. This will typically happen when a timezone
+     * other than the local timezone is used (calculating Los Angeles sunset using a GMT timezone for example). In this
+     * case the sunset date will be incremented to the following date.
+     *
+     * @return the <code>Instant</code> representing the exact sunset time. If the calculation can't be computed such as in
+     *         the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it
+     *         does not set, a <code>null</code> will be returned. See detailed explanation on top of the page.
+     * @see AstronomicalCalculator#adjustZenith
+     * @see #getSeaLevelSunset()
+     * @see AstronomicalCalendar#getUTCSunset
+     */
+    public Instant getSunsetWithElevation() {
+        double sunset = getUTCSunset(GEOMETRIC_ZENITH);
+        if (Double.isNaN(sunset)) {
+            return null;
+        } else {
+            return getInstantFromTime(sunset, SolarEvent.SUNSET);
+        }
+    }
+
 	/**
-	 * The getSunset method returns a <code>Instant</code> representing the
-	 * {@link AstronomicalCalculator#getElevationAdjustment(double) elevation adjusted} sunset time. The zenith used for
-	 * the calculation uses {@link #GEOMETRIC_ZENITH geometric zenith} of 90&deg; plus
-	 * {@link AstronomicalCalculator#getElevationAdjustment(double)}. This is adjusted by the
-	 * {@link AstronomicalCalculator} to add approximately 50/60 of a degree to account for 34 archminutes of refraction
-	 * and 16 archminutes for the sun's radius for a total of {@link AstronomicalCalculator#adjustZenith 90.83333&deg;}.
-	 * See documentation for the specific implementation of the {@link AstronomicalCalculator} that you are using. Note:
-	 * In certain cases the calculates sunset will occur before sunrise. This will typically happen when a timezone
-	 * other than the local timezone is used (calculating Los Angeles sunset using a GMT timezone for example). In this
-	 * case the sunset date will be incremented to the following date.
-	 * 
+     * @deprecated Use {@link #getSunsetWithElevation()} instead.
+     * This method already accounts for the observer's elevation, but its name
+     * does not clearly reflect that behavior. The replacement method provides
+     * a more accurate and descriptive name.
+     *
 	 * @return the <code>Instant</code> representing the exact sunset time. If the calculation can't be computed such as in
 	 *         the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it
 	 *         does not set, a <code>null</code> will be returned. See detailed explanation on top of the page.
 	 * @see AstronomicalCalculator#adjustZenith
 	 * @see #getSeaLevelSunset()
 	 * @see AstronomicalCalendar#getUTCSunset
 	 */
+    @Deprecated(forRemoval = false)
 	public Instant getSunset() {
 		double sunset = getUTCSunset(GEOMETRIC_ZENITH);
 		if (Double.isNaN(sunset)) {
@@ -233,9 +276,9 @@ public Instant getSunset() {
 	 * @return the <code>Instant</code> representing the exact sea-level sunset time. If the calculation can't be computed
 	 *         such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one
 	 *         where it does not set, a <code>null</code> will be returned. See detailed explanation on top of the page.
-	 * @see AstronomicalCalendar#getSunset
+	 * @see AstronomicalCalendar#getSunsetWithElevation
 	 * @see AstronomicalCalendar#getUTCSeaLevelSunset
-	 * @see #getSunset()
+	 * @see #getSunsetWithElevation()
 	 */
 	public Instant getSeaLevelSunset() {
 		double sunset = getUTCSeaLevelSunset(GEOMETRIC_ZENITH);
@@ -317,15 +360,15 @@ public static Instant getTimeOffset(Instant time, long offsetMillis) {
 
 	/**
 	 * A utility method that returns the time of an offset by degrees below or above the horizon of
-	 * {@link #getSunrise() sunrise}. Note that the degree offset is from the vertical, so for a calculation of 14&deg;
+	 * {@link #getSunriseWithElevation() sunrise}. Note that the degree offset is from the vertical, so for a calculation of 14&deg;
 	 * before sunrise, an offset of 14 + {@link #GEOMETRIC_ZENITH} = 104 would have to be passed as a parameter.
 	 * 
 	 * @param offsetZenith
-	 *            the degrees before {@link #getSunrise()} to use in the calculation. For time after sunrise use
+	 *            the degrees before {@link #getSunriseWithElevation()} to use in the calculation. For time after sunrise use
 	 *            negative numbers. Note that the degree offset is from the vertical, so for a calculation of 14&deg;
 	 *            before sunrise, an offset of 14 + {@link #GEOMETRIC_ZENITH} = 104 would have to be passed as a
 	 *            parameter.
-	 * @return The {@link java.time.Instant} of the offset after (or before) {@link #getSunrise()}. If the calculation
+	 * @return The {@link java.time.Instant} of the offset after (or before) {@link #getSunriseWithElevation()}. If the calculation
 	 *         can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does
 	 *         not rise, and one where it does not set, a <code>null</code> will be returned. See detailed explanation
 	 *         on top of the page.
@@ -337,15 +380,15 @@ public Instant getSunriseOffsetByDegrees(double offsetZenith) {
 	}
 
 	/**
-	 * A utility method that returns the time of an offset by degrees below or above the horizon of {@link #getSunset()
+	 * A utility method that returns the time of an offset by degrees below or above the horizon of {@link #getSunsetWithElevation()
 	 * sunset}. Note that the degree offset is from the vertical, so for a calculation of 14&deg; after sunset, an
 	 * offset of 14 + {@link #GEOMETRIC_ZENITH} = 104 would have to be passed as a parameter.
 	 * 
 	 * @param offsetZenith
-	 *            the degrees after {@link #getSunset()} to use in the calculation. For time before sunset use negative
+	 *            the degrees after {@link #getSunsetWithElevation()} to use in the calculation. For time before sunset use negative
 	 *            numbers. Note that the degree offset is from the vertical, so for a calculation of 14&deg; after
 	 *            sunset, an offset of 14 + {@link #GEOMETRIC_ZENITH} = 104 would have to be passed as a parameter.
-	 * @return The {@link java.time.Instant} of the offset after (or before) {@link #getSunset()}. If the calculation can't
+	 * @return The {@link java.time.Instant} of the offset after (or before) {@link #getSunsetWithElevation()}. If the calculation can't
 	 *         be computed such as in the Arctic Circle where there is at least one day a year where the sun does not
 	 *         rise, and one where it does not set, a <code>null</code> will be returned. See detailed explanation on
 	 *         top of the page.
@@ -466,8 +509,8 @@ public long getTemporalHour() {
 	/**
 	 * A utility method that will allow the calculation of a temporal (solar) hour based on the sunrise and sunset
 	 * passed as parameters to this method. An example of the use of this method would be the calculation of a
-	 * elevation adjusted temporal hour by passing in {@link #getSunrise() sunrise} and
-	 * {@link #getSunset() sunset} as parameters.
+	 * elevation adjusted temporal hour by passing in {@link #getSunriseWithElevation() sunrise} and
+	 * {@link #getSunsetWithElevation() sunset} as parameters.
 	 * 
 	 * @param startOfDay
 	 *            The start of the day.