From e5b8a333bd7c68c71cd0a46e625319b3581290c6 Mon Sep 17 00:00:00 2001 From: Henri Sivonen Date: Fri, 3 Oct 2025 12:12:38 +0300 Subject: [PATCH 1/2] Point out that AstronomicalSimulation exists for semver and users who are unsure probably want UmmAlQura instead. Fixes #6210 --- components/calendar/src/cal/hijri.rs | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/components/calendar/src/cal/hijri.rs b/components/calendar/src/cal/hijri.rs index 5b8a299c3df..4a93b5c40bd 100644 --- a/components/calendar/src/cal/hijri.rs +++ b/components/calendar/src/cal/hijri.rs @@ -98,7 +98,9 @@ pub trait Rules: Clone + Debug + crate::cal::scaffold::UnstableSealed { /// [`Hijri`] [`Rules`] based on an astronomical simulation for a particular location. /// /// These simulations are known to not necessarily match sightings on the ground, -/// but are included for completeness. +/// and are included for semver reasons rather than use case reasons. Unless you know +/// otherwise for sure, instead of this variant, use `UmmAlQura`, which uses the results +/// of KACST's Mecca-based calculations. #[derive(Copy, Clone, Debug)] pub struct AstronomicalSimulation { pub(crate) location: SimulatedLocation, @@ -380,7 +382,11 @@ impl Hijri { Self::new_simulated_mecca() } - /// Creates a [`Hijri`] calendar using simulated sightings at Mecca. + /// Creates a [`Hijri`] calendar using simulated sightings at Mecca. The + /// simulation in not official and this variant is provided for semver rather + /// than use case reasons. Unless you know otherwise for sure, instead of + /// this variant, use `Hijri::new_umm_al_qura`, which uses the results of + /// KACST's Mecca-based calculations. pub const fn new_simulated_mecca() -> Self { Self(AstronomicalSimulation { location: SimulatedLocation::Mecca, From 821bc16875b7bff7fbdeca8fccb0cd00eb31299a Mon Sep 17 00:00:00 2001 From: Henri Sivonen Date: Mon, 6 Oct 2025 09:50:37 +0300 Subject: [PATCH 2/2] Avoid mentioning semver or use cases --- components/calendar/src/cal/hijri.rs | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/components/calendar/src/cal/hijri.rs b/components/calendar/src/cal/hijri.rs index 4a93b5c40bd..f4b2d5033c6 100644 --- a/components/calendar/src/cal/hijri.rs +++ b/components/calendar/src/cal/hijri.rs @@ -97,10 +97,9 @@ pub trait Rules: Clone + Debug + crate::cal::scaffold::UnstableSealed { /// [`Hijri`] [`Rules`] based on an astronomical simulation for a particular location. /// -/// These simulations are known to not necessarily match sightings on the ground, -/// and are included for semver reasons rather than use case reasons. Unless you know -/// otherwise for sure, instead of this variant, use `UmmAlQura`, which uses the results -/// of KACST's Mecca-based calculations. +/// 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. #[derive(Copy, Clone, Debug)] pub struct AstronomicalSimulation { pub(crate) location: SimulatedLocation, @@ -382,11 +381,11 @@ impl Hijri { Self::new_simulated_mecca() } - /// Creates a [`Hijri`] calendar using simulated sightings at Mecca. The - /// simulation in not official and this variant is provided for semver rather - /// than use case reasons. Unless you know otherwise for sure, instead of - /// this variant, use `Hijri::new_umm_al_qura`, which uses the results of - /// KACST's Mecca-based calculations. + /// Creates a [`Hijri`] calendar using simulated sightings at Mecca. + /// + /// 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 + /// [`Hijri::new_umm_al_qura`], which uses the results of KACST's Mecca-based calculations. pub const fn new_simulated_mecca() -> Self { Self(AstronomicalSimulation { location: SimulatedLocation::Mecca,