Clarify inconsistent GltfConvertCoordinates 0.18 behavior

crates/bevy_gltf/src/loader/mod.rs

@@ -151,6 +151,20 @@ pub struct GltfLoader {
     pub default_sampler: Arc<Mutex<ImageSamplerDescriptor>>,
     /// The default glTF coordinate conversion setting. This can be overridden
     /// per-load by [`GltfLoaderSettings::convert_coordinates`].
+    ///
+    /// Setting any of these values to true will result in the relevant entities
+    /// moving in opposite directions when using the forward direction.
+    /// This means that within a scene, different entities in a hierarchy will
+    /// move in different global directions when using the forward direction
+    /// for that `Entity`.
+    ///
+    /// For example, a parent `Entity` A, with a child `Entity` B that has a `Mesh3d`
+    /// component:
+    ///
+    /// - Entity A with a `Transform`
+    ///   - Entity B with a `Transform`, `Mesh3d`, `MeshMaterial3d`
+    ///
+    /// If A's forward moves "North", B's forward moves "South"
     pub default_convert_coordinates: GltfConvertCoordinates,
     /// glTF extension data processors.
     /// These are Bevy-side processors designed to access glTF
@@ -204,6 +218,20 @@ pub struct GltfLoaderSettings {
     /// Overrides the default glTF coordinate conversion setting.
     ///
     /// If `None`, uses the global default set by [`GltfPlugin::convert_coordinates`](crate::GltfPlugin::convert_coordinates).
+    ///
+    /// Setting any of these values to true will result in the relevant entities
+    /// moving in opposite directions when using the forward direction.
+    /// This means that within a scene, different entities in a hierarchy will
+    /// move in different global directions when using the forward direction
+    /// for that `Entity`.
+    ///
+    /// For example, a parent `Entity` A, with a child `Entity` B that has a `Mesh3d`
+    /// component:
+    ///
+    /// - Entity A with a `Transform`
+    ///   - Entity B with a `Transform`, `Mesh3d`, `MeshMaterial3d`
+    ///
+    /// If A's forward moves "North", B's forward moves "South"
     pub convert_coordinates: Option<GltfConvertCoordinates>,
 }