Finish documenting bevy_gltf (#9998)

# Objective

- Finish documenting `bevy_gltf`.

## Solution

- Document the remaining items, add links to the glTF spec where
relevant. Add the `warn(missing_doc)` attribute.

crates/bevy_gltf/src/lib.rs

@@ -1,4 +1,9 @@
+//! Plugin providing an [`AssetLoader`](bevy_asset::AssetLoader) and type definitions
+//! for loading glTF 2.0 (a standard 3D scene definition format) files in Bevy.
+//!
+//! The [glTF 2.0 specification](https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html) defines the format of the glTF files.
 #![allow(clippy::type_complexity)]
+#![warn(missing_docs)]
 
 #[cfg(feature = "bevy_animation")]
 use bevy_animation::AnimationClip;
@@ -27,6 +32,11 @@ pub struct GltfPlugin {
 }
 
 impl GltfPlugin {
+    /// Register a custom vertex attribute so that it is recognized when loading a glTF file with the [`GltfLoader`].
+    ///
+    /// `name` must be the attribute name as found in the glTF data, which must start with an underscore.
+    /// See [this section of the glTF specification](https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html#meshes-overview)
+    /// for additional details on custom attributes.
     pub fn add_custom_vertex_attribute(
         mut self,
         name: &str,
@@ -64,50 +74,81 @@ impl Plugin for GltfPlugin {
 /// Representation of a loaded glTF file.
 #[derive(Asset, Debug, TypePath)]
 pub struct Gltf {
+    /// All scenes loaded from the glTF file.
     pub scenes: Vec<Handle<Scene>>,
+    /// Named scenes loaded from the glTF file.
     pub named_scenes: HashMap<String, Handle<Scene>>,
+    /// All meshes loaded from the glTF file.
     pub meshes: Vec<Handle<GltfMesh>>,
+    /// Named meshes loaded from the glTF file.
     pub named_meshes: HashMap<String, Handle<GltfMesh>>,
+    /// All materials loaded from the glTF file.
     pub materials: Vec<Handle<StandardMaterial>>,
+    /// Named materials loaded from the glTF file.
     pub named_materials: HashMap<String, Handle<StandardMaterial>>,
+    /// All nodes loaded from the glTF file.
     pub nodes: Vec<Handle<GltfNode>>,
+    /// Named nodes loaded from the glTF file.
     pub named_nodes: HashMap<String, Handle<GltfNode>>,
+    /// Default scene to be displayed.
     pub default_scene: Option<Handle<Scene>>,
+    /// All animations loaded from the glTF file.
     #[cfg(feature = "bevy_animation")]
     pub animations: Vec<Handle<AnimationClip>>,
+    /// Named animations loaded from the glTF file.
     #[cfg(feature = "bevy_animation")]
     pub named_animations: HashMap<String, Handle<AnimationClip>>,
 }
 
 /// A glTF node with all of its child nodes, its [`GltfMesh`],
 /// [`Transform`](bevy_transform::prelude::Transform) and an optional [`GltfExtras`].
+///
+/// See [the relevant glTF specification section](https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html#reference-node).
 #[derive(Asset, Debug, Clone, TypePath)]
 pub struct GltfNode {
+    /// Direct children of the node.
     pub children: Vec<GltfNode>,
+    /// Mesh of the node.
     pub mesh: Option<Handle<GltfMesh>>,
+    /// Local transform.
     pub transform: bevy_transform::prelude::Transform,
+    /// Additional data.
     pub extras: Option<GltfExtras>,
 }
 
 /// A glTF mesh, which may consist of multiple [`GltfPrimitives`](GltfPrimitive)
 /// and an optional [`GltfExtras`].
+///
+/// See [the relevant glTF specification section](https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html#reference-mesh).
 #[derive(Asset, Debug, Clone, TypePath)]
 pub struct GltfMesh {
+    /// Primitives of the glTF mesh.
     pub primitives: Vec<GltfPrimitive>,
+    /// Additional data.
     pub extras: Option<GltfExtras>,
 }
 
 /// Part of a [`GltfMesh`] that consists of a [`Mesh`], an optional [`StandardMaterial`] and [`GltfExtras`].
+///
+/// See [the relevant glTF specification section](https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html#reference-mesh-primitive).
 #[derive(Asset, Debug, Clone, TypePath)]
 pub struct GltfPrimitive {
+    /// Topology to be rendered.
     pub mesh: Handle<Mesh>,
+    /// Material to apply to the `mesh`.
     pub material: Option<Handle<StandardMaterial>>,
+    /// Additional data.
     pub extras: Option<GltfExtras>,
+    /// Additional data of the `material`.
     pub material_extras: Option<GltfExtras>,
 }
 
+/// Additional untyped data that can be present on most glTF types.
+///
+/// See [the relevant glTF specification section](https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html#reference-extras).
 #[derive(Clone, Debug, Reflect, Default, Component)]
 #[reflect(Component)]
 pub struct GltfExtras {
+    /// Content of the extra data.
     pub value: String,
 }

crates/bevy_gltf/src/loader.rs

@@ -49,35 +49,56 @@ use thiserror::Error;
 /// An error that occurs when loading a glTF file.
 #[derive(Error, Debug)]
 pub enum GltfError {
+    /// Unsupported primitive mode.
     #[error("unsupported primitive mode")]
-    UnsupportedPrimitive { mode: Mode },
+    UnsupportedPrimitive {
+        /// The primitive mode.
+        mode: Mode,
+    },
+    /// Invalid glTF file.
     #[error("invalid glTF file: {0}")]
     Gltf(#[from] gltf::Error),
+    /// Binary blob is missing.
     #[error("binary blob is missing")]
     MissingBlob,
+    /// Decoding the base64 mesh data failed.
     #[error("failed to decode base64 mesh data")]
     Base64Decode(#[from] base64::DecodeError),
+    /// Unsupported buffer format.
     #[error("unsupported buffer format")]
     BufferFormatUnsupported,
+    /// Invalid image mime type.
     #[error("invalid image mime type: {0}")]
     InvalidImageMimeType(String),
+    /// Error when loading a texture. Might be due to a disabled image file format feature.
     #[error("You may need to add the feature for the file format: {0}")]
     ImageError(#[from] TextureError),
+    /// Failed to read bytes from an asset path.
     #[error("failed to read bytes from an asset path: {0}")]
     ReadAssetBytesError(#[from] ReadAssetBytesError),
+    /// Failed to load asset from an asset path.
     #[error("failed to load asset from an asset path: {0}")]
     AssetLoadError(#[from] AssetLoadError),
+    /// Missing sampler for an animation.
     #[error("Missing sampler for animation {0}")]
     MissingAnimationSampler(usize),
+    /// Failed to generate tangents.
     #[error("failed to generate tangents: {0}")]
     GenerateTangentsError(#[from] bevy_render::mesh::GenerateTangentsError),
+    /// Failed to generate morph targets.
     #[error("failed to generate morph targets: {0}")]
     MorphTarget(#[from] bevy_render::mesh::morph::MorphBuildError),
 }
 
 /// Loads glTF files with all of their data as their corresponding bevy representations.
 pub struct GltfLoader {
+    /// List of compressed image formats handled by the loader.
     pub supported_compressed_formats: CompressedImageFormats,
+    /// Custom vertex attributes that will be recognized when loading a glTF file.
+    ///
+    /// Keys must be the attribute names as found in the glTF data, which must start with an underscore.
+    /// See [this section of the glTF specification](https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html#meshes-overview)
+    /// for additional details on custom attributes.
     pub custom_vertex_attributes: HashMap<String, MeshVertexAttribute>,
 }