Add some documentation to standard material fields (#5323)

# Objective

the bevy pbr shader doesn't handle at all normal maps
if a mesh doesn't have backed tangents. This is a pitfall
(that I fell into) and needs to be documented.

# Solution

Document the behavior. (Also document a few other
`StandardMaterial` fields)

## Changelog

* Add documentation to `emissive`, `normal_map_texture` and `occlusion_texture` fields of `StandardMaterial`.

crates/bevy_pbr/src/pbr_material.rs

@@ -24,9 +24,24 @@ pub struct StandardMaterial {
     #[texture(1)]
     #[sampler(2)]
     pub base_color_texture: Option<Handle<Image>>,
+
     // Use a color for user friendliness even though we technically don't use the alpha channel
     // Might be used in the future for exposure correction in HDR
+    /// Color the material "emits" to the camera.
+    ///
+    /// This is typically used for monitor screens or LED lights.
+    /// Anything that can be visible even in darkness.
+    ///
+    /// The emissive color is added to what would otherwise be the material's visible color.
+    /// This means that for a light emissive value, in darkness,
+    /// you will mostly see the emissive component.
+    ///
+    /// The default emissive color is black, which doesn't add anything to the material color.
+    ///
+    /// Note that **an emissive material won't light up surrounding areas like a light source**,
+    /// it just adds a value to the color seen on screen.
     pub emissive: Color,
+
     #[texture(3)]
     #[sampler(4)]
     pub emissive_texture: Option<Handle<Image>>,
@@ -39,21 +54,55 @@ pub struct StandardMaterial {
     /// If used together with a roughness/metallic texture, this is factored into the final base
     /// color as `metallic * metallic_texture_value`
     pub metallic: f32,
+
     #[texture(5)]
     #[sampler(6)]
     pub metallic_roughness_texture: Option<Handle<Image>>,
     /// Specular intensity for non-metals on a linear scale of [0.0, 1.0]
     /// defaults to 0.5 which is mapped to 4% reflectance in the shader
     pub reflectance: f32,
+
+    /// Used to fake the lighting of bumps and dents on a material.
+    ///
+    /// A typical usage would be faking cobblestones on a flat plane mesh in 3D.
+    ///
+    /// # Notes
+    ///
+    ///
+    /// Normal mapping with `StandardMaterial` and the core bevy PBR shaders requires:
+    /// - A normal map texture
+    /// - Vertex UVs
+    /// - Vertex tangents
+    /// - Vertex normals
+    ///
+    /// Tangents do not have to be stored in your model,
+    /// they can be generated using the [`Mesh::generate_tangents`] method.
+    /// If your material has a normal map, but still renders as a flat surface,
+    /// make sure your meshes have their tangents set.
+    ///
+    /// [`Mesh::generate_tangents`]: bevy_render::mesh::Mesh::generate_tangents
     #[texture(9)]
     #[sampler(10)]
     pub normal_map_texture: Option<Handle<Image>>,
+
     /// Normal map textures authored for DirectX have their y-component flipped. Set this to flip
     /// it to right-handed conventions.
     pub flip_normal_map_y: bool,
+
+    /// Specifies the level of exposure to ambient light.
+    ///
+    /// This is usually generated and stored automatically ("baked") by 3D-modelling software.
+    ///
+    /// Typically, steep concave parts of a model (such as the armpit of a shirt) are darker,
+    /// because they have little exposed to light.
+    /// An occlusion map specifies those parts of the model that light doesn't reach well.
+    ///
+    /// The material will be less lit in places where this texture is dark.
+    /// This is similar to ambient occlusion, but built into the model.
     #[texture(7)]
     #[sampler(8)]
     pub occlusion_texture: Option<Handle<Image>>,
+
     /// Support two-sided lighting by automatically flipping the normals for "back" faces
     /// within the PBR lighting shader.
     /// Defaults to false.