Fix documentatation

crates/bevy_pbr/src/pbr_material.rs

@@ -303,9 +303,9 @@ pub struct StandardMaterial {
     /// If you are seeing jaggy edges, increase this value.
     /// However, this incurs a performance cost.
     ///
-    /// Dependent on the situation, switching to [`ParallaxMappingMethod::ReliefMapping`]
+    /// Dependent on the situation, switching to [`ParallaxMappingMethod::Relief`]
     /// and keeping this value low might have better performance than increasing the
-    /// layer count while using [`ParallaxMappingMethod::ParallaxOcclusionMapping`].
+    /// layer count while using [`ParallaxMappingMethod::Occlusion`].
     ///
     /// Default is `16.0`.
     pub max_parallax_layer_count: f32,
@@ -431,7 +431,7 @@ pub struct StandardMaterialUniform {
     /// If your `parallax_depth_scale` is >0.1 and you are seeing jaggy edges,
     /// increase this value. However, this incurs a performance cost.
     pub max_parallax_layer_count: f32,
-    /// Using [`ParallaxMappingMethod::ReliefMapping`], how many additional
+    /// Using [`ParallaxMappingMethod::Relief`], how many additional
     /// steps to use at most to find the depth value.
     pub max_relief_mapping_search_steps: u32,
 }

examples/3d/parallax_mapping.rs

@@ -331,14 +331,21 @@ fn setup(
 #[derive(Resource)]
 struct Normal(Option<Handle<Image>>);
 
-/// Work around the fact that the default bevy image loader sets the
-/// normal's format to something incompatible with normal shaders.
-/// The format must be one of the `TextureFormat` ending in `*Unorm`.
+/// Work around the default bevy image loader.
 ///
-/// In this function, we wait until the image is loaded, immediately
-/// change its format and never run the core logic afterward.
+/// The bevy image loader used by `AssetServer` always loads images in
+/// `Srgb` mode, which is usually what it should do,
+/// but is incompatible with normal maps.
 ///
-/// Without proper format, lighting looks wrong.
+/// Normal maps require a texture in linear color space,
+/// so we overwrite the format of the normal map we loaded through `AssetServer`
+/// in this system.
+///
+/// Note that this method of conversion is a last resort workaround. You should
+/// get your normal maps from a 3d model file, like gltf.
+///
+/// In this system, we wait until the image is loaded, immediately
+/// change its format and never run the logic afterward.
 fn update_normal(
     mut already_ran: Local<bool>,
     mut images: ResMut<Assets<Image>>,