Skip to content

Commit 9d29276

Browse files
MenoDataMenoData
committed
better documentation
see issue #977
1 parent 7f7340b commit 9d29276

File tree

1 file changed

+47
-9
lines changed

1 file changed

+47
-9
lines changed

‎base/src/main/java/net/time4j/calendar/astro/SolarTime.java‎

Lines changed: 47 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
/*
22
* -----------------------------------------------------------------------
3-
* Copyright © 2013-2021 Meno Hochschild, <http://www.menodata.de/>
3+
* Copyright © 2013-2023 Meno Hochschild, <http://www.menodata.de/>
44
* -----------------------------------------------------------------------
55
* This file (SolarTime.java) is part of project Time4J.
66
*
@@ -1850,6 +1850,9 @@ public interface Calculator {
18501850

18511851
/**
18521852
* <p>Calculates the moment of sunrise. </p>
1853+
*
1854+
* <p>The zenith angle can be represented by the result of the method
1855+
* {@link #getZenithAngle(double, int) getZenithAngle(latitude, altitude)}. </p>
18531856
*
18541857
* @param date the local calendar date
18551858
* @param latitude geographical latitude in degrees, positive for North, negative for South
@@ -1861,6 +1864,10 @@ public interface Calculator {
18611864
/*[deutsch]
18621865
* <p>Berechnet den Zeitpunkt des Sonnenaufgangs. </p>
18631866
*
1867+
* <p>Der Zenitwinkel kann mittels des Ergebnisses der Methode
1868+
* {@link #getZenithAngle(double, int) getZenithAngle(latitude, altitude)}
1869+
* berechnet werden. </p>
1870+
*
18641871
* @param date the local calendar date
18651872
* @param latitude geographical latitude in degrees, positive for North, negative for South
18661873
* @param longitude geographical longitude in degrees, positive for East, negative for West
@@ -1878,6 +1885,9 @@ Optional<Moment> sunrise(
18781885
/**
18791886
* <p>Calculates the moment of sunset. </p>
18801887
*
1888+
* <p>The zenith angle can be represented by the result of the method
1889+
* {@link #getZenithAngle(double, int) getZenithAngle(latitude, altitude)}. </p>
1890+
*
18811891
* @param date the local calendar date
18821892
* @param latitude geographical latitude in degrees, positive for North, negative for South
18831893
* @param longitude geographical longitude in degrees, positive for East, negative for West
@@ -1888,6 +1898,10 @@ Optional<Moment> sunrise(
18881898
/*[deutsch]
18891899
* <p>Berechnet den Zeitpunkt des Sonnenuntergangs. </p>
18901900
*
1901+
* <p>Der Zenitwinkel kann mittels des Ergebnisses der Methode
1902+
* {@link #getZenithAngle(double, int) getZenithAngle(latitude, altitude)}
1903+
* berechnet werden. </p>
1904+
*
18911905
* @param date the local calendar date
18921906
* @param latitude geographical latitude in degrees, positive for North, negative for South
18931907
* @param longitude geographical longitude in degrees, positive for East, negative for West
@@ -1949,21 +1963,28 @@ default double getFeature(
19491963
/**
19501964
* <p>Calculates the additional geodetic angle due to the extra altitude of the observer. </p>
19511965
*
1952-
* <p>The default implementation just returns {@code 0.0}. </p>
1966+
* <p>The default implementation just returns {@code 0.0}. Negative altitudes modelling
1967+
* a valley between hight mountains are not supported but might be approximated by an angle
1968+
* calculation using the altitude difference between valley and mountain and also using
1969+
* the distance between valley and mountain resulting in a negative angle. </p>
19531970
*
19541971
* @param latitude the geographical latitude in degrees
1955-
* @param altitude the altitude of the observer in meters
1972+
* @param altitude the altitude of the observer in meters, not negative
19561973
* @return geodetic angle correction in degrees
19571974
* @since 3.36/4.31
19581975
*/
19591976
/*[deutsch]
19601977
* <p>Berechnet die zus&auml;tzliche geod&auml;tische Winkelkorrektur, die der H&ouml;he
19611978
* des Beobachters auf der Erdoberfl&auml;che geschuldet ist. </p>
19621979
*
1963-
* <p>Die Standardimplementierung liefert nur {@code 0.0}. </p>
1980+
* <p>Die Standardimplementierung liefert nur {@code 0.0}. Negative H&ouml;hen, die ein
1981+
* Tal zwischen hohen Bergen modellieren, werden nicht unterst&uuml;tzt. Eine solche
1982+
* Ausnahmesituation mu&szlig; durch eine Winkelberechnung mit der H&ouml;hendifferenz
1983+
* zwischen Berg und Tal sowie der Entfernung Berg-Tal gel&ouml;st werden, resultierend
1984+
* in einem negativen Winkel. </p>
19641985
*
19651986
* @param latitude the geographical latitude in degrees
1966-
* @param altitude the altitude of the observer in meters
1987+
* @param altitude the altitude of the observer in meters, not negative
19671988
* @return geodetic angle correction in degrees
19681989
* @since 3.36/4.31
19691990
*/
@@ -1980,10 +2001,19 @@ default double getGeodeticAngle(
19802001
* <p>Calculates the angle of the sun relative to the zenith at sunrise or sunset. </p>
19812002
*
19822003
* <p>The default implementation just uses the standard refraction angle of 34 arc minutes,
1983-
* adds to it {@code 90°} and the {@link #getGeodeticAngle(double, int) geodetic angle correction}. </p>
2004+
* adds to it {@code 90°} and the {@link #getGeodeticAngle(double, int) geodetic angle correction}.
2005+
* In case users do not want to take into account the geodetic angle correction, they might simply
2006+
* subtract latter one. Example for the situation of Denver in USA which is suited in a valley with
2007+
* far mountain ranges: </p>
2008+
*
2009+
* <pre>
2010+
* double zenith =
2011+
* calculator.getZenithAngle(latitude, altitude)
2012+
* - calculator.getGeodeticAngle(latitude, altitude);
2013+
* </pre>
19842014
*
19852015
* @param latitude the geographical latitude in degrees
1986-
* @param altitude the altitude of the observer in meters
2016+
* @param altitude the altitude of the observer in meters, not negative
19872017
* @return effective zenith angle in degrees
19882018
* @since 3.36/4.31
19892019
*/
@@ -1992,10 +2022,18 @@ default double getGeodeticAngle(
19922022
*
19932023
* <p>Die Standardimplementierung verwendet nur den normalen Refraktionswinkel von 34 Bogenminuten und
19942024
* addiert dazu {@code 90°} und die {@link #getGeodeticAngle(double, int) geod&auml;tische Winkelkorrektur}.
1995-
* </p>
2025+
* Wird als Zenitwinkel eine Implementierung ohne Ber&uuml;cksichtigung der geod&auml;tischen
2026+
* Winkelkorrektur gew&uuml;nscht, darf letztere einfach subtrahiert werden. Beispiel f&uuml;r die
2027+
* Situation von Denver in den USA, das in einem weiten Tal mit fernen Bergketten gelegen ist: </p>
2028+
*
2029+
* <pre>
2030+
* double zenith =
2031+
* calculator.getZenithAngle(latitude, altitude)
2032+
* - calculator.getGeodeticAngle(latitude, altitude);
2033+
* </pre>
19962034
*
19972035
* @param latitude the geographical latitude in degrees
1998-
* @param altitude the altitude of the observer in meters
2036+
* @param altitude the altitude of the observer in meters, not negative
19992037
* @return effective zenith angle in degrees
20002038
* @since 3.36/4.31
20012039
*/

0 commit comments

Comments
 (0)