Point out that AstronomicalSimulation is unofficial and users who are unsure probably want UmmAlQura instead (#7031)

Fixes #6210

Author: hsivonen

components/calendar/src/cal/hijri.rs

@@ -97,8 +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,
-/// but are included for completeness.
+/// 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,
@@ -386,6 +387,10 @@ impl Hijri<AstronomicalSimulation> {
     }
 
     /// 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,