Improve the docs of Hijri AstronomicalSimulation

components/calendar/src/cal/hijri.rs

@@ -57,6 +57,19 @@ mod ummalqura_data;
 ///
 /// There are either 6 or 7 30-day months, so the length of the year is 354 or 355 days.
 ///
+/// # Crescent moon visibility
+///
+/// According to Islam, months begin when an observer first sees the crescent moon.
+///
+/// For centuries, astronomers have been developing criteria for predicting crescent moon
+/// visibility. However, most regions that use the Hijri calendar rely on observations that
+/// are impacted by atmospheric phenomena, meaning such predictions are only an approximation
+/// of ground truth.
+///
+/// The primary exception is Saudi Arabia, where the KACST uses sophisticated telescopes to
+/// make the observations more reliable. They publish predictions covering multiple centuries;
+/// see [`UmmAlQura`].
+///
 /// # Calendar drift
 ///
 /// As a lunar calendar, this calendar does not intend to follow the solar year, and drifts more
@@ -129,19 +142,27 @@ pub trait Rules: Clone + Debug + crate::cal::scaffold::UnstableSealed {
 
 /// [`Hijri`] [`Rules`] based on an astronomical simulation for a particular location.
 ///
-/// These simulations are unofficial and are known to not necessarily match sightings
-/// on the ground. Unless you know otherwise for sure, instead of this variant, use
-/// [`UmmAlQura`], which uses the results of KACST's Mecca-based calculations.
+/// If your goal is to match ground truth in Saudi Arabia, use [`UmmAlQura`] instead.
 ///
-/// As floating point arithmetic degenerates for far-away dates, this falls back to
-/// the tabular calendar at some point.
+/// These rules are based on calculations of the Earth, moon, and sun along with the
+/// Shaukat criterion to determine crescent moon visibility.[^1]
+///
+/// These rules can form the basis of a custom [`Rules`] implementation that includes
+/// crescent sighting adjustments. As discussed in the [`Hijri`] documentation, using these
+/// rules without allowing such adjustments will produce dates that are only approximations
+/// of the ground truth.
+///
+/// The simulations are pre-computed for Gregorian years 1900 to 2140, falling back to
+/// a tabular approximation outside that range.
 ///
 /// The precise behavior of this calendar may change in the future if:
 /// - We decide to tweak the precise astronomical simulation used
 /// - We decide to expand or reduce the range where we are using the astronomical simulation.
 ///
 /// This corresponds to the `"islamic-rgsa"` [CLDR calendar](https://unicode.org/reports/tr35/#UnicodeCalendarIdentifier)
 /// if constructed with [`Hijri::new_simulated_mecca()`].
+///
+/// [^1]: See [calendrical_calculations::islamic::observational_islamic_from_fixed]
 #[derive(Copy, Clone, Debug, PartialEq, Eq)]
 pub struct AstronomicalSimulation {
     pub(crate) location: SimulatedLocation,

utils/calendrical_calculations/src/islamic.rs

@@ -55,7 +55,13 @@ pub fn fixed_from_observational_islamic(
         - 1
 }
 
+/// Calculates an Islamic date from a [`RataDie`] and [`Location`].
+///
+/// This uses the phasis criterion proposed by S. K. Shaukat[^1], explained in Reingold section 14.9.
+///
 /// Lisp code reference: <https://github.com/EdReingold/calendar-code2/blob/1ee51ecfaae6f856b0d7de3e36e9042100b4f424/calendar.l#L6983-L6995>
+///
+/// [^1]: K. Abdali, O. Afzal, I. A. Ahmad, M. Durrani, A. Salama, and S. K. Shaukat, “Crescent Moon Visibility: Consensus on Moon-Sighting and Determination of an Islamic Calendar,” manuscript, 1996.
 pub fn observational_islamic_from_fixed(date: RataDie, location: Location) -> (i32, u8, u8) {
     let lunar_phase = Astronomical::calculate_new_moon_at_or_before(date);
     let crescent = Astronomical::phasis_on_or_before(date, location, Some(lunar_phase));