doc

Signed-off-by: Mattias Andrée <maandree@operamail.com>

2 files changed, 67 insertions, 17 deletions

diff --git a/info/blueshift.texinfo b/info/blueshift.texinfo
index be30aad..4b3dce1 100644
--- a/info/blueshift.texinfo
+++ b/info/blueshift.texinfo
@@ -1372,6 +1372,15 @@ geographical position (@code{latitude}, @code{longitude}).
 Calculates the same thing as @code{solar_elevation_from_time},
 except the time is optional and defaults to the current time.
 
+@item have_sunrise_and_sunset(latitude, t = None)
+Determine whether you have sunrise and sunsets.
+
+@item is_summer(latitude, t = None)
+Determine whether it is summer.
+
+@item is_winter(latitude, t = None)
+Determine whether it is winter.
+
 @item future_past_elevation(delta, latitude, longitude, elevation, t = None)
 Calculates the next or previous point in time the Sun's
 elevation will be @code{elevation} degrees or was
@@ -1379,12 +1388,12 @@ elevation will be @code{elevation} degrees or was
 (@code{latitude}, @code{longitude}). The calculated
 timepoint may actually be the current time, @code{t}.
 If not time point can be found within a Julian year
-@code{None} will be returned. This function uses
-interpolation to determine time point, because inverting
+@code{None} will be returned. This function uses binary
+search to determine time point, because inverting
 @code{solar_elevation} is unfeasible to do algebraically;
 @code{delta} specified the size of the steps between the
 timepoints that are tested to determine the timespan in
-which to do the interpolation.
+which to do the binary search.
 
 @item future_elevation(latitude, longitude, elevation, t = None)
 Calculates the next point in time the Sun's elevation will
@@ -1401,6 +1410,61 @@ Calculates the previous point in time the Sun's elevation was
 timepoint may actually be the current time, @code{t}.
 If not time point can be found within a Julian year
 @code{None} will be returned. This function uses
+
+@item future_past_elevation_derivative(delta, latitude, longitude, derivative, t = None)
+Similar to @code{future_past_elevation}, but calculates the
+time point for a first derivative of the solar elevation.
+
+@item future_elevation_derivative(latitude, longitude, derivative, t = None)
+Similar to @code{future_elevation}, but calculates the
+time point for a first derivative of the solar elevation.
+
+@item past_elevation_derivative(latitude, longitude, derivative, t = None)
+Similar to @code{past_elevation}, but calculates the
+time point for a first derivative of the solar elevation.
+
+@item future_past_equinox(delta, t = None)
+Similar to @code{future_past_elevation}, but calculates the
+time point for an equinox. The result cannot be @code{None}.
+
+@item future_equinox(t = None)
+Similar to @code{future_elevation}, but calculates the
+time point for an equinox. The result cannot be @code{None}.
+
+@item past_equinox(t = None)
+Similar to @code{past_elevation}, but calculates the
+time point for an equinox. The result cannot be @code{None}.
+
+@item future_past_solstice(delta, t = None)
+Similar to @code{future_past_elevation}, but calculates the
+time point for a solstice. The result cannot be @code{None}.
+
+@item future_solstice(t = None)
+Similar to @code{future_elevation}, but calculates the
+time point for a solstice. The result cannot be @code{None}.
+
+@item past_solstice(t = None)
+Similar to @code{past_elevation}, but calculates the
+time point for a solstice. The result cannot be @code{None}.
+
+@item solar_prediction(delta, requested, fun, epsilon = 0.000001, span = 0.01, t = None)
+Predict the time point of the next or previous
+time an arbitrary condition is meet by way of
+binary searching. This conditions is satisfied if
+@code{fun} of a timepoint equals @code{requested}
+with a tolerance of @code{epsilon}.
+@code{delta} specified the size of the steps between the
+timepoints that are tested to determine the timespan in
+which to do the binary search. This timespan is limited
+to @code{span} with is a timespan in Julian Centuries;
+0,01 is approximately one Gregorian year.
+If no satisfactory timepoint can be found
+within the specified span @code{None} is returned.
+
+@item ptime(t)
+Prints a time, input in the Julian Centuries format,
+as a human-readable local time.
+
 @end table
 
 For all functions beneath @code{degrees}, @code{t} is the
diff --git a/src/solar.py b/src/solar.py
index 1cdf017..38fa11b 100644
--- a/src/solar.py
+++ b/src/solar.py
@@ -468,7 +468,6 @@ def solar_elevation(latitude, longitude, t = None):
 
 
 
-# TODO document
 def have_sunrise_and_sunset(latitude, t = None):
     '''
     Determine whether solar declination currently is
@@ -494,7 +493,6 @@ def have_sunrise_and_sunset(latitude, t = None):
         return -90 - d < latitude < 90 + d
 
 
-# TODO document
 def is_summer(latitude, t = None):
     '''
     Determine whether it is summer
@@ -511,7 +509,6 @@ def is_summer(latitude, t = None):
     return (d > 0) == (latitude > 0)
 
 
-# TODO document
 def is_winter(latitude, t = None):
     '''
     Determine whether it is winter
@@ -529,7 +526,6 @@ def is_winter(latitude, t = None):
 
 
 
-# TODO document
 def solar_prediction(delta, requested, fun, epsilon = 0.000001, span = 0.01, t = None):
     '''
     Predict the time point of the next or previous
@@ -583,7 +579,6 @@ def solar_prediction(delta, requested, fun, epsilon = 0.000001, span = 0.01, t =
 
 
 
-# TODO document
 def future_past_equinox(delta, t = None):
     '''
     Predict the time point of the next or previous equinox
@@ -597,7 +592,6 @@ def future_past_equinox(delta, t = None):
     return solar_prediction(delta, 0, solar_declination, t = t)
 
 
-# TODO document
 def future_equinox(t = None):
     '''
     Predict the time point of the next equinox
@@ -611,7 +605,6 @@ def future_equinox(t = None):
     return future_past_equinox(0.01 / 2000, t)
     
 
-# TODO document
 def past_equinox(t = None):
     '''
     Predict the time point of the previous equinox
@@ -626,7 +619,6 @@ def past_equinox(t = None):
 
 
 
-# TODO document
 def future_past_solstice(delta, t = None):
     '''
     Predict the time point of the next or previous solstice
@@ -643,7 +635,6 @@ def future_past_solstice(delta, t = None):
     return solar_prediction(delta, 0, dfun, t = t)
 
 
-# TODO document
 def future_solstice(t = None):
     '''
     Predict the time point of the next solstice
@@ -655,7 +646,6 @@ def future_solstice(t = None):
     return future_past_solstice(0.01 / 2000, t)
     
 
-# TODO document
 def past_solstice(t = None):
     '''
     Predict the time point of the previous solstice
@@ -726,7 +716,6 @@ def past_elevation(latitude, longitude, elevation, t = None):
 
 
 
-# TODO document
 def future_past_elevation_derivative(delta, latitude, longitude, derivative, t = None):
     '''
     Predict the time point of the next or previous time the
@@ -749,7 +738,6 @@ def future_past_elevation_derivative(delta, latitude, longitude, derivative, t =
     return solar_prediction(delta, derivative, dfun, t = t)
 
 
-# TODO document
 def future_elevation_derivative(latitude, longitude, derivative, t = None):
     '''
     Predict the time point of the next time the
@@ -768,7 +756,6 @@ def future_elevation_derivative(latitude, longitude, derivative, t = None):
     return future_past_elevation_derivative(0.01 / 2000, latitude, longitude, derivative, t)
     
 
-# TODO document
 def past_elevation_derivative(latitude, longitude, derivative, t = None):
     '''
     Predict the time point of the previous time
@@ -831,7 +818,6 @@ def sunrise_equation(latitude, longitude, t = None):
 
 
 
-# TODO document
 def ptime(t):
     '''
     Print a time stamp in human-readable local time