From e58b223e8608d3edf0074546582f3f9e19f3194d Mon Sep 17 00:00:00 2001 From: Elyahu Date: Mon, 8 Jan 2024 15:56:19 -0700 Subject: [PATCH] finish documentation --- .../KosherSwift/AstronomicalCalendar.swift | 8 +-- .../util/AstronomicalCalculator.swift | 66 ++++++++----------- Sources/KosherSwift/util/GeoLocation.swift | 23 +++---- Sources/KosherSwift/util/NOAACalculator.swift | 63 +++++++----------- .../KosherSwift/util/SunTimesCalculator.swift | 9 +-- Sources/KosherSwift/util/Time.swift | 11 ++-- Sources/KosherSwift/util/Zman.swift | 46 ++++++------- .../KosherSwift/util/ZmanimFormatter.swift | 4 +- 8 files changed, 100 insertions(+), 130 deletions(-) diff --git a/Sources/KosherSwift/AstronomicalCalendar.swift b/Sources/KosherSwift/AstronomicalCalendar.swift index 4ff17aa..b58e479 100644 --- a/Sources/KosherSwift/AstronomicalCalendar.swift +++ b/Sources/KosherSwift/AstronomicalCalendar.swift @@ -155,7 +155,7 @@ public class AstronomicalCalendar { * the calculation uses ``GEOMETRIC_ZENITH`` geometric zenith of 90° plus * ``AstronomicalCalculator.getElevationAdjustment(double)``. This is adjusted by the * ``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°}. + * and 16 archminutes for the sun's radius for a total of ``AstronomicalCalculator.adjustZenith`` 90.83333°. * See documentation for the specific implementation of the ``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 @@ -187,7 +187,7 @@ public class AstronomicalCalendar { * 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 nil will be returned. See detailed explanation on top of the page. * @see AstronomicalCalendar#getSunset - * @see AstronomicalCalendar#getUTCSeaLevelSunset 2see {@link #getSunset()} + * @see AstronomicalCalendar#getUTCSeaLevelSunset 2see ``getSunset()`` */ public func getSeaLevelSunset() -> Date? { let sunset = getUTCSeaLevelSunset(zenith: AstronomicalCalendar.GEOMETRIC_ZENITH); @@ -348,7 +348,7 @@ public class AstronomicalCalendar { * the degrees below the horizon. For time after sunrise use negative numbers. * @return The time in the format: 18.75 for 18:45:00 UTC/GMT. 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, {@link Double#NaN} will be returned. See detailed explanation on top of the page. + * not set, ``Double.nan`` will be returned. See detailed explanation on top of the page. */ public func getUTCSunrise(zenith:Double) -> Double { return getAstronomicalCalculator().getUTCSunrise(date: workingDate, geoLocation: getGeoLocation(), zenith: zenith, adjustForElevation: true); @@ -364,7 +364,7 @@ public class AstronomicalCalendar { * the degrees below the horizon. For time after sunrise use negative numbers. * @return The time in the format: 18.75 for 18:45:00 UTC/GMT. 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, {@link Double#NaN} will be returned. See detailed explanation on top of the page. + * not set, ``Double.nan`` will be returned. See detailed explanation on top of the page. * @see AstronomicalCalendar#getUTCSunrise * @see AstronomicalCalendar#getUTCSeaLevelSunset */ diff --git a/Sources/KosherSwift/util/AstronomicalCalculator.swift b/Sources/KosherSwift/util/AstronomicalCalculator.swift index 2f6f273..f1fb4c3 100644 --- a/Sources/KosherSwift/util/AstronomicalCalculator.swift +++ b/Sources/KosherSwift/util/AstronomicalCalculator.swift @@ -10,8 +10,8 @@ import Foundation /** * An abstract class that all sun time calculating classes extend. This allows the algorithm used to be changed at * runtime, easily allowing comparison the results of using different algorithms. - * @todo Consider methods that would allow atmospheric modeling. This can currently be adjusted by {@link - * #setRefraction(double) setting the refraction}. + * + * //todo Consider methods that would allow atmospheric modeling. This can currently be adjusted by ``setRefraction(refraction:)`` setting the refraction. * * @author © Eliyahu Hershfeld 2004 - 2023 */ @@ -65,12 +65,12 @@ public class AstronomicalCalculator { public static let GEOMETRIC_ZENITH = 90.0; /** - * Returns the default class for calculating sunrise and sunset. This is currently the {@link NOAACalculator}, + * Returns the default class for calculating sunrise and sunset. This is currently the ``NOAACalculator``, * but this may change. The NOAACalculator is the most accurate sunrise/sunset calculator that is currently available. * It should be prefered over the SunTimesCalculator. * * @return AstronomicalCalculator the default class for calculating sunrise and sunset. In the current - * implementation the default calculator returned is the {@link NOAACalculator}. + * implementation the default calculator returned is the ``NOAACalculator``. */ public static func getDefault(geoLocation: GeoLocation) -> AstronomicalCalculator { return NOAACalculator(geoLocation: geoLocation); @@ -80,22 +80,14 @@ public class AstronomicalCalculator { * Method to return the adjustment to the zenith required to account for the elevation. Since a person at a higher * elevation can see farther below the horizon, the calculation for sunrise / sunset is calculated below the horizon * used at sea level. This is only used for sunrise and sunset and not times before or after it such as - * {@link com.kosherjava.zmanim.AstronomicalCalendar#getBeginNauticalTwilight() nautical twilight} since those + * ``AstronomicalCalendar.getBeginNauticalTwilight()`` nautical twilight since those * calculations are based on the level of available light at the given dip below the horizon, something that is not - * affected by elevation, the adjustment should only made if the zenith == 90° {@link #adjustZenith adjusted} - * for refraction and solar radius. The algorithm used is - * - * 
-     * elevationAdjustment = Math.toDegrees(Math.acos(earthRadiusInMeters / (earthRadiusInMeters + elevationMeters)));
-     *
+ * affected by elevation, the adjustment should only made if the zenith == 90° ``adjustZenith`` adjusted + * for refraction and solar radius. The algorithm used is: elevationAdjustment = Math.toDegrees(Math.acos(earthRadiusInMeters / (earthRadiusInMeters + elevationMeters))); * * The source of this algorithm is Calendrical Calculations by Edward M. * Reingold and Nachum Dershowitz. An alternate algorithm that produces an almost identical (but not accurate) - * result found in Ma'aglay Tzedek by Moishe Kosower and other sources is: - * - * 
-     * elevationAdjustment = 0.0347 * Math.sqrt(elevationMeters);
-     *
+ * result found in Ma'aglay Tzedek by Moishe Kosower and other sources is: elevationAdjustment = 0.0347 x Math.sqrt(elevationMeters); * * @param elevation * elevation in Meters. @@ -114,28 +106,28 @@ public class AstronomicalCalculator { * is not a point, and because the atmosphere refracts light, this 90° zenith does not, in fact, correspond to * true sunset or sunrise, instead the center of the Sun's disk must lie just below the horizon for the upper edge * to be obscured. This means that a zenith of just above 90° must be used. The Sun subtends an angle of 16 - * minutes of arc (this can be changed via the {@link #setSolarRadius(double)} method , and atmospheric refraction - * accounts for 34 minutes or so (this can be changed via the {@link #setRefraction(double)} method), giving a total + * minutes of arc (this can be changed via the ``setSolarRadius(solarRadius:)`` method , and atmospheric refraction + * accounts for 34 minutes or so (this can be changed via the ``setRefraction(refraction:)`` method), giving a total * of 50 arcminutes. The total value for ZENITH is 90+(5/6) or 90.8333333° for true sunrise/sunset. Since a * person at an elevation can see blow the horizon of a person at sea level, this will also adjust the zenith to * account for elevation if available. Note that this will only adjust the value if the zenith is exactly 90 degrees. * For values below and above this no correction is done. As an example, astronomical twilight is when the sun is - * 18° below the horizon or {@link com.kosherjava.zmanim.AstronomicalCalendar#ASTRONOMICAL_ZENITH 108° - * below the zenith}. This is traditionally calculated with none of the above mentioned adjustments. The same goes + * 18° below the horizon or ``AstronomicalCalendar.ASTRONOMICAL_ZENITH`` 108° + * below the zenith. This is traditionally calculated with none of the above mentioned adjustments. The same goes * for various tzais and alos times such as the - * {@link com.kosherjava.zmanim.ZmanimCalendar#ZENITH_16_POINT_1 16.1°} dip used in - * {@link com.kosherjava.zmanim.ComplexZmanimCalendar#getAlos16Point1Degrees()}. + * ``ZmanimCalendar.ZENITH_16_POINT_1`` 16.1° dip used in + * ``ComplexZmanimCalendar.getAlos16Point1Degrees()``. * * @param zenith - * the azimuth below the vertical zenith of 90°. For sunset typically the {@link #adjustZenith - * zenith} used for the calculation uses geometric zenith of 90° and {@link #adjustZenith adjusts} + * the azimuth below the vertical zenith of 90°. For sunset typically the ``adjustZenith`` + * zenith used for the calculation uses geometric zenith of 90° and ``adjustZenith`` adjusts * this slightly to account for solar refraction and the sun's radius. Another example would be - * {@link com.kosherjava.zmanim.AstronomicalCalendar#getEndNauticalTwilight()} that passes - * {@link com.kosherjava.zmanim.AstronomicalCalendar#NAUTICAL_ZENITH} to this method. + * ``AstronomicalCalendar.getEndNauticalTwilight()`` that passes + * ``AstronomicalCalendar.NAUTICAL_ZENITH`` to this method. * @param elevation * elevation in Meters. - * @return The zenith adjusted to include the {@link #getSolarRadius sun's radius}, {@link #getRefraction - * refraction} and {@link #getElevationAdjustment elevation} adjustment. This will only be adjusted for + * @return The zenith adjusted to include the ``getSolarRadius()`` sun's radius, ``getRefraction()`` + * refraction and ``getElevationAdjustment`` elevation adjustment. This will only be adjusted for * sunrise and sunset (if the zenith == 90°) * @see #getElevationAdjustment(double) */ @@ -149,9 +141,7 @@ public class AstronomicalCalculator { /** * Method to get the refraction value to be used when calculating sunrise and sunset. The default value is 34 arc - * minutes. The Errata and Notes for Calendrical Calculations: The Millennium Edition by Edward M. Reingold and Nachum Dershowitz + * minutes. The Errata and Notes for Calendrical Calculations: The Millennium Edition by Edward M. Reingold and Nachum Dershowitz * lists the actual average refraction value as 34.478885263888294 or approximately 34' 29". The refraction value as well * as the solarRadius and elevation adjustment are added to the zenith used to calculate sunrise and sunset. * @@ -206,21 +196,17 @@ public class AstronomicalCalculator { self.solarRadius = solarRadius; } - /* - Do not use this method directly, it must be overrided by sub classes like the NOAACalculator class - */ + ///Do not use this method directly, it must be overrided by sub classes like the NOAACalculator class public func getUTCSunrise(date: Date, geoLocation: GeoLocation, zenith: Double, adjustForElevation: Bool) -> Double { return Double.nan } - /* - Do not use this method directly, it must be overrided by sub classes like the NOAACalculator class - */ + + ///Do not use this method directly, it must be overrided by sub classes like the NOAACalculator class public func getUTCSunset(date: Date, geoLocation: GeoLocation, zenith: Double, adjustForElevation: Bool) -> Double { return Double.nan } - /* - Do not use this method directly, it must be overrided by sub classes like the NOAACalculator class - */ + + ///Do not use this method directly, it must be overrided by sub classes like the NOAACalculator class public func getUTCNoon(date: Date, geoLocation: GeoLocation) -> Double { return Double.nan } diff --git a/Sources/KosherSwift/util/GeoLocation.swift b/Sources/KosherSwift/util/GeoLocation.swift index 613446e..6b916db 100644 --- a/Sources/KosherSwift/util/GeoLocation.swift +++ b/Sources/KosherSwift/util/GeoLocation.swift @@ -10,7 +10,7 @@ import Foundation /** * A class that contains location information such as latitude and longitude required for astronomical calculations. The * elevation field may not be used by some calculation engines and would be ignored if set. Check the documentation for - * specific implementations of the {@link AstronomicalCalculator} to see if elevation is calculated as part of the + * specific implementations of the ``AstronomicalCalculator`` to see if elevation is calculated as part of the * algorithm. * * @author © Eliyahu Hershfeld 2004 - 2022 @@ -98,7 +98,7 @@ public class GeoLocation { * GeoLocation constructor with parameters for all required fields. * * @param name - * The location name for display use such as "Lakewood, NJ" + * The location name for display use such as "Lakewood, NJ". This can be an empty string as well * @param latitude * the latitude in a double format such as 40.095965 for Lakewood, NJ. * Note: For latitudes south of the equator, a negative value should be used. @@ -121,7 +121,7 @@ public class GeoLocation { * GeoLocation constructor with parameters for all required fields. * * @param name - * The location name for display use such as "Lakewood, NJ" + * The location name for display use such as "Lakewood, NJ". This can be an empty string as well * @param latitude * the latitude in a double format such as 40.095965 for Lakewood, NJ. * Note: For latitudes south of the equator, a negative value should be used. @@ -278,12 +278,7 @@ public class GeoLocation { } /** - * Method to set the TimeZone. If this is ever set after the GeoLocation is set in the - * {@link com.kosherjava.zmanim.AstronomicalCalendar}, it is critical that - * {@link com.kosherjava.zmanim.AstronomicalCalendar#getCalendar()}. - * {@link java.util.Calendar#setTimeZone(TimeZone) setTimeZone(TimeZone)} be called in order for the - * AstronomicalCalendar to output times in the expected offset. This situation will arise if the - * AstronomicalCalendar is ever {@link com.kosherjava.zmanim.AstronomicalCalendar#clone() cloned}. + * Method to set the TimeZone. * * @param timeZone * The timeZone to set. @@ -293,11 +288,11 @@ public class GeoLocation { } /** - * This method is not tested at all. If you want to use this method or fix it, please submit an issue on github. + * This method is not tested at all. If you want to use this method or fix it, please submit an issue on the KosherSwift github. * A method that will return the location's local mean time offset in milliseconds from local standard time. The globe is split into 360°, with * 15° per hour of the day. For a local that is at a longitude that is evenly divisible by 15 (longitude % 15 == - * 0), at solar {@link com.kosherjava.zmanim.AstronomicalCalendar#getSunTransit() noon} (with adjustment for the equation of time) the sun should be directly overhead, * so a user who is 1° west of this will have noon at 4 minutes after standard time noon, and conversely, a user * who is 1° east of the 15° longitude will have noon at 11:56 AM. Lakewood, N.J., whose longitude is @@ -311,7 +306,7 @@ public class GeoLocation { * @since 1.1 */ public func getLocalMeanTimeOffset() -> Double { - //This method might not work properly. I did not test it at all. + //This method might not work properly. I did not test it at all as it is not currently used anywhere in the codebase return Double(Int(getLongitude()) * 4 * GeoLocation.MINUTE_MILLIS - getTimeZone().secondsFromGMT()); } @@ -401,8 +396,8 @@ public class GeoLocation { * @param location * the destination location * @param formula - * This formula calculates initial bearing ({@link #INITIAL_BEARING}), final bearing ( - * {@link #FINAL_BEARING}) and distance ({@link #DISTANCE}). + * This formula calculates initial bearing (``INITIAL_BEARING``), final bearing ( + * ``FINAL_BEARING``) and distance (``DISTANCE``). * @return geodesic distance in Meters */ private func vincentyFormula(location: GeoLocation, formula: Int) -> Double { diff --git a/Sources/KosherSwift/util/NOAACalculator.swift b/Sources/KosherSwift/util/NOAACalculator.swift index 607825c..c2295bc 100644 --- a/Sources/KosherSwift/util/NOAACalculator.swift +++ b/Sources/KosherSwift/util/NOAACalculator.swift @@ -52,35 +52,23 @@ public class NOAACalculator : AstronomicalCalculator { } /** - * Returns the name of the algorithm. - * - * @return the descriptive name of the algorithm. - */ + * Returns the name of the algorithm. + * @return the descriptive name of the algorithm. + */ public func getCalculatorName() -> String { return "US National Oceanic and Atmospheric Administration Algorithm"; } /** - * A method that calculates UTC sunrise as well as any time based on an angle above or below sunrise. This abstract - * method is implemented by the classes that extend this class. - * - * @param calendar - * Used to calculate day of year. - * @param geoLocation - * The location information used for astronomical calculating sun times. - * @param zenith - * the azimuth below the vertical zenith of 90 degrees. for sunrise typically the {@link #adjustZenith - * zenith} used for the calculation uses geometric zenith of 90° and {@link #adjustZenith adjusts} - * this slightly to account for solar refraction and the sun's radius. Another example would be - * {@link com.kosherjava.zmanim.AstronomicalCalendar#getBeginNauticalTwilight()} that passes - * {@link com.kosherjava.zmanim.AstronomicalCalendar#NAUTICAL_ZENITH} to this method. - * @param adjustForElevation - * Should the time be adjusted for elevation - * @return The UTC time of sunrise in 24 hour format. 5:45:00 AM will return 5.75.0. If an error was encountered in - * the calculation (expected behavior for some locations such as near the poles, - * {@link java.lang.Double#NaN} will be returned. - * @see #getElevationAdjustment(double) - */ + A method that calculates UTC sunrise as well as any time based on an angle above or below sunrise. This abstract method is implemented by the classes that extend this class. + @param calendar Used to calculate day of year. + @param geoLocation The location information used for astronomical calculating sun times. + @param zenith the azimuth below the vertical zenith of 90 degrees. for sunrise typically the ``adjustZenith`` zenith used for the calculation uses geometric zenith of 90° and ``adjustZenith`` adjusts this slightly to account for solar refraction and the sun's radius. Another example would be ``AstronomicalCalendar.getBeginNauticalTwilight()`` that passes ``AstronomicalCalendar.NAUTICAL_ZENITH`` to this method. + @param adjustForElevation Should the time be adjusted for elevation + @return The UTC time of sunrise in 24 hour format. 5:45:00 AM will return 5.75.0. If an error was encountered in + the calculation (expected behavior for some locations such as near the poles, ``Double.nan`` will be returned. + @see #getElevationAdjustment(double) + */ public override func getUTCSunrise(date: Date, geoLocation: GeoLocation, zenith: Double, adjustForElevation: Bool) -> Double { let elevation = adjustForElevation ? geoLocation.getElevation() : 0; let adjustedZenith = adjustZenith(zenith: zenith, elevation: elevation); @@ -107,16 +95,16 @@ public class NOAACalculator : AstronomicalCalculator { * @param geoLocation * The location information used for astronomical calculating sun times. * @param zenith - * the azimuth below the vertical zenith of 90°. For sunset typically the {@link #adjustZenith - * zenith} used for the calculation uses geometric zenith of 90° and {@link #adjustZenith adjusts} + * the azimuth below the vertical zenith of 90°. For sunset typically the ``adjustZenith`` + * zenith used for the calculation uses geometric zenith of 90° and ``adjustZenith`` adjusts * this slightly to account for solar refraction and the sun's radius. Another example would be - * {@link com.kosherjava.zmanim.AstronomicalCalendar#getEndNauticalTwilight()} that passes - * {@link com.kosherjava.zmanim.AstronomicalCalendar#NAUTICAL_ZENITH} to this method. + * ``AstronomicalCalendar.getEndNauticalTwilight()`` that passes + * ``AstronomicalCalendar.NAUTICAL_ZENITH`` to this method. * @param adjustForElevation * Should the time be adjusted for elevation * @return The UTC time of sunset in 24 hour format. 5:45:00 AM will return 5.75.0. If an error was encountered in * the calculation (expected behavior for some locations such as near the poles, - * {@link java.lang.Double#NaN} will be returned. + * ``Double.nan`` will be returned. * @see #getElevationAdjustment(double) */ public override func getUTCSunset(date: Date, geoLocation: GeoLocation, zenith: Double, adjustForElevation: Bool) -> Double { @@ -137,10 +125,10 @@ public class NOAACalculator : AstronomicalCalculator { } /** - * Return the Julian day from a Java Calendar + * Return the Julian day from a Swift Date * - * @param calendar - * The Java Calendar + * @param date + * The Swift Date * @return the Julian day corresponding to the date Note: Number is returned for start of day. Fractional days * should be added later. */ @@ -394,8 +382,7 @@ public class NOAACalculator : AstronomicalCalculator { /** * Returns the hour angle of the sun in radiansat sunset for the latitude. - * @todo use - {@link #getSunHourAngleAtSunrise(double, double, double)} implementation to avoid - * duplication of code. + * @todo use - {@link #getSunHourAngleAtSunrise(double, double, double)} implementation to avoid duplication of code. * * @param lat * the latitude of observer in degrees @@ -418,7 +405,7 @@ public class NOAACalculator : AstronomicalCalculator { * horizontal coordinate system at the given location at the given time. Can be negative if the sun is below the * horizon. Not corrected for altitude. * - * @param cal + * @param date * time of calculation * @param lat * latitude of location for calculation @@ -455,7 +442,7 @@ public class NOAACalculator : AstronomicalCalculator { * horizontal coordinate system at the given location at the given time. Not corrected for altitude. True south is 0 * degrees. * - * @param cal + * @param date * time of calculation * @param lat * latitude of location for calculation @@ -544,8 +531,8 @@ public class NOAACalculator : AstronomicalCalculator { * @see com.kosherjava.zmanim.util.AstronomicalCalculator#getUTCNoon(Calendar, GeoLocation) * @see #getSolarNoonUTC(double, double) * - * @param calendar - * The Calendar representing the date to calculate solar noon for + * @param date + * The Date representing the date to calculate solar noon for * @param geoLocation * The location information used for astronomical calculating sun times. This class uses only requires * the longitude for calculating noon since it is the same time anywhere along the longitude line. diff --git a/Sources/KosherSwift/util/SunTimesCalculator.swift b/Sources/KosherSwift/util/SunTimesCalculator.swift index 3f727cb..ff37a6b 100644 --- a/Sources/KosherSwift/util/SunTimesCalculator.swift +++ b/Sources/KosherSwift/util/SunTimesCalculator.swift @@ -13,8 +13,8 @@ import Foundation * Boone that is based on the US Naval Observatory'sAstronomical Almanac and used with his permission. Added to Kevin's * code is adjustment of the zenith to account for elevation. This algorithm returns the same time every year and does not - * account for leap years. It is not as accurate as the Jean Meeus based {@link NOAACalculator} that is the default calculator - * use by the KosherJava zmanim library. + * account for leap years. It is not as accurate as the Jean Meeus based ``NOAACalculator`` that is the default calculator + * use by the KosherJava/KosherSwift zmanim libraries. * * @author © Eliyahu Hershfeld 2004 - 2023 * @author © Kevin Boone 2000 @@ -32,6 +32,7 @@ public class SunTimesCalculator : AstronomicalCalculator { } /** + * Returns the name of this calculator * @see com.kosherjava.zmanim.util.AstronomicalCalculator#getCalculatorName() */ public func getCalculatorName() -> String { @@ -258,7 +259,7 @@ public class SunTimesCalculator : AstronomicalCalculator { * Return the Universal Coordinated Time (UTC) * of solar noon for the given day at the given location * on earth. This implementation returns solar noon as the time halfway between sunrise and sunset. - * {@link NOAACalculator}, the default calculator, returns true solar noon. See The Definition of Chatzos for details on solar * noon calculations. * @see com.kosherjava.zmanim.util.AstronomicalCalculator#getUTCNoon(Calendar, GeoLocation) @@ -269,7 +270,7 @@ public class SunTimesCalculator : AstronomicalCalculator { * @param geoLocation * The location information used for astronomical calculating sun times. * @return the time in minutes from zero UTC. If an error was encountered in the calculation (expected behavior for - * some locations such as near the poles, {@link Double#NaN} will be returned. + * some locations such as near the poles, ``Double.nan`` will be returned. */ public override func getUTCNoon(date:Date, geoLocation:GeoLocation) -> Double { let sunrise = getUTCSunrise(date: date, geoLocation: geoLocation, zenith: 90, adjustForElevation: false); diff --git a/Sources/KosherSwift/util/Time.swift b/Sources/KosherSwift/util/Time.swift index 89e5f7b..c92a983 100644 --- a/Sources/KosherSwift/util/Time.swift +++ b/Sources/KosherSwift/util/Time.swift @@ -8,13 +8,14 @@ import Foundation /** - * A class that represents a numeric time. Times that represent a time of day are stored as {@link java.util.Date}s in + * A class that represents a numeric time. Times that represent a time of day are stored as ``Date``s in * this API. The time class is used to represent numeric time such as the time in hours, minutes, seconds and - * milliseconds of a {@link com.kosherjava.zmanim.AstronomicalCalendar#getTemporalHour() temporal hour}. + * milliseconds of a ``AstronomicalCalendar.getTemporalHour()`` temporal hour. * * @author © Eliyahu Hershfeld 2004 - 2020 */ public class Time { + /** milliseconds in a second. */ private static let SECOND_MILLIS = 1000; @@ -67,7 +68,7 @@ public class Time { /** * Constructor with a parameter for milliseconds. This constructor casts the milliseconds to an int and - * calls {@link #Time(int)} + * calls ``init(millis:)`` * @param millis the milliseconds to set the object with. */ public convenience init(millis:Double) { @@ -76,7 +77,7 @@ public class Time { /** * A constructor that sets the time by milliseconds. The milliseconds are converted to hours, minutes, seconds - * and milliseconds. If the milliseconds are negative it will call {@link #setIsNegative(boolean)}. + * and milliseconds. If the milliseconds are negative it will call ``setIsNegative(isNegative:)``. * @param millis the milliseconds to set. */ public init(millis:Int) { @@ -98,7 +99,7 @@ public class Time { } /** - * Does the time represent a negative time 9such as using this to subtract time from another Time. + * Does the time represent a negative time such as using this to subtract time from another Time. * @return if the time is negative. */ public func getIsNegative() -> Bool { diff --git a/Sources/KosherSwift/util/Zman.swift b/Sources/KosherSwift/util/Zman.swift index 69c7bde..715a699 100644 --- a/Sources/KosherSwift/util/Zman.swift +++ b/Sources/KosherSwift/util/Zman.swift @@ -55,14 +55,14 @@ public class Zman { public var label:String; /** - * The {@link Date} of the zman + * The Date of the zman */ public var zman:Date?; /** - * The duration if the zman is a {@link com.kosherjava.zmanim.AstronomicalCalendar#getTemporalHour() temporal hour} (or the various - * shaah zmanis base times such as {@link com.kosherjava.zmanim.ZmanimCalendar#getShaahZmanisGra() shaah Zmanis GRA} or - * {@link com.kosherjava.zmanim.ComplexZmanimCalendar#getShaahZmanis16Point1Degrees() shaah Zmanis 16.1°}). + * The duration if the zman is a ``AstronomicalCalendar.getTemporalHour()`` temporal hour (or the various + * shaah zmanis base times such as ``ZmanimCalendar.getShaahZmanisGra()`` shaah Zmanis GRA or + * ``ComplexZmanimCalendar.getShaahZmanis16Point1Degrees()`` shaah Zmanis 16.1°). */ public var duration:Int64; @@ -72,7 +72,7 @@ public class Zman { public var description:String; /** - * The constructor setting a {@link Date} based zman and a label. + * The constructor setting a ``Date`` based zman and a label. * @param date the Date of the zman. * @param label the label of the zman such as "Sof Zman Krias Shema GRA". * @see #Zman(long, String) @@ -86,10 +86,10 @@ public class Zman { /** * The constructor setting a duration based zman such as - * {@link com.kosherjava.zmanim.AstronomicalCalendar#getTemporalHour() temporal hour} (or the various shaah zmanis times such as - * {@link com.kosherjava.zmanim.ZmanimCalendar#getShaahZmanisGra() shaah zmanis GRA} or - * {@link com.kosherjava.zmanim.ComplexZmanimCalendar#getShaahZmanis16Point1Degrees() shaah Zmanis 16.1°}) and label. - * @param duration a duration based zman such as ({@link com.kosherjava.zmanim.AstronomicalCalendar#getTemporalHour()} + * ``AstronomicalCalendar.getTemporalHour()`` temporal hour (or the various shaah zmanis times such as + * ``ZmanimCalendar.getShaahZmanisGra()`` shaah zmanis GRA or + * ``ComplexZmanimCalendar.getShaahZmanis16Point1Degrees()`` shaah Zmanis 16.1°) and label. + * @param duration a duration based zman such as (``AstronomicalCalendar.getTemporalHour()`` * @param label the label of the zman such as "Shaah Zmanis GRA". * @see #Zman(Date, String) */ @@ -100,7 +100,7 @@ public class Zman { } /** - * Returns the {@code Date} based zman. + * Returns the Date based zman. * @return the zman. * @see #setZman(Date) */ @@ -109,7 +109,7 @@ public class Zman { } /** - * Sets a {@code Date} based zman. + * Sets a Date based zman. * @param date a {@code Date} based zman * @see #getZman() */ @@ -118,9 +118,9 @@ public class Zman { } /** - * Returns a duration based zman such as {@link com.kosherjava.zmanim.AstronomicalCalendar#getTemporalHour() temporal hour} - * (or the various shaah zmanis times such as {@link com.kosherjava.zmanim.ZmanimCalendar#getShaahZmanisGra() shaah zmanis GRA} - * or {@link com.kosherjava.zmanim.ComplexZmanimCalendar#getShaahZmanis16Point1Degrees() shaah zmanis 16.1°}). + * Returns a duration based zman such as ``AstronomicalCalendar#getTemporalHour()`` temporal hour + * (or the various shaah zmanis times such as ``ZmanimCalendar.getShaahZmanisGra()`` shaah zmanis GRA + * or ``ComplexZmanimCalendar.getShaahZmanis16Point1Degrees()`` shaah zmanis 16.1°). * @return the duration based zman. * @see #setDuration(long) */ @@ -129,10 +129,10 @@ public class Zman { } /** - * Sets a duration based zman such as {@link com.kosherjava.zmanim.AstronomicalCalendar#getTemporalHour() temporal hour} - * (or the various shaah zmanis times as {@link com.kosherjava.zmanim.ZmanimCalendar#getShaahZmanisGra() shaah zmanis GRA} or - * {@link com.kosherjava.zmanim.ComplexZmanimCalendar#getShaahZmanis16Point1Degrees() shaah zmanis 16.1°}). - * @param duration duration based zman such as {@link com.kosherjava.zmanim.AstronomicalCalendar#getTemporalHour()}. + * Sets a duration based zman such as ``AstronomicalCalendar.getTemporalHour()`` temporal hour + * (or the various shaah zmanis times as ``ZmanimCalendar.getShaahZmanisGra()`` shaah zmanis GRA or + * ``ComplexZmanimCalendar.getShaahZmanis16Point1Degrees()`` shaah zmanis 16.1°). + * @param duration duration based zman such as ``AstronomicalCalendar#getTemporalHour()``. * @see #getDuration() */ public func setDuration(duration:Int64) { @@ -141,7 +141,7 @@ public class Zman { /** * Returns the name / label of the zman such as "Sof Zman Krias Shema GRA". There are no automatically set labels - * and you must set them using {@link #setLabel(String)}. + * and you must set them using ``setLabel(label:)``. * @return the name/label of the zman. * @see #setLabel(String) */ @@ -160,7 +160,7 @@ public class Zman { /** * Returns the longer description or explanation of a zman. There is no default value for this and it must be set using - * {@link #setDescription(String)} + * ``setDescription(description:)`` * @return the description or explanation of a zman. * @see #setDescription(String) */ @@ -209,9 +209,9 @@ public class Zman { /** * A {@link Comparator} that will compare and sort duration based zmanim such as - * {@link com.kosherjava.zmanim.AstronomicalCalendar#getTemporalHour() temporal hour} (or the various shaah zmanis times - * such as {@link com.kosherjava.zmanim.ZmanimCalendar#getShaahZmanisGra() shaah zmanis GRA} or - * {@link com.kosherjava.zmanim.ComplexZmanimCalendar#getShaahZmanis16Point1Degrees() shaah zmanis 16.1°}). Returns a negative + * ``AstronomicalCalendar#getTemporalHour()`` temporal hour (or the various shaah zmanis times + * such as ``ZmanimCalendar#getShaahZmanisGra()`` shaah zmanis GRA or + * ``ComplexZmanimCalendar#getShaahZmanis16Point1Degrees()`` shaah zmanis 16.1°). Returns a negative * integer, zero, or a positive integer as the first argument is less than, equal to, or greater than the second. * Please note that this class will will sort cases where {@code Zman} is a null. */ diff --git a/Sources/KosherSwift/util/ZmanimFormatter.swift b/Sources/KosherSwift/util/ZmanimFormatter.swift index f5935de..1a169b6 100644 --- a/Sources/KosherSwift/util/ZmanimFormatter.swift +++ b/Sources/KosherSwift/util/ZmanimFormatter.swift @@ -8,8 +8,8 @@ import Foundation /** - * A class used to format both non {@link java.util.Date} times generated by the Zmanim package as well as Dates. For - * example the {@link com.kosherjava.zmanim.AstronomicalCalendar#getTemporalHour()} returns the length of the hour in + * A class used to format both non ``Date`` times generated by the Zmanim package as well as Dates. For + * example the ``AstronomicalCalendar.getTemporalHour()`` returns the length of the hour in * milliseconds. This class can format this time. * * @author © Eliyahu Hershfeld 2004 - 2022