Add missing docs reported by rustdoc

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "phobos"
-version = "0.7.2"
+version = "0.7.3"
 edition = "2021"
 license = "Apache-2.0"
 description = "Fast, powerful Vulkan abstraction library"

src/command_buffer/traits.rs

@@ -1,3 +1,5 @@
+//! Defines the traits with command buffer operations
+
 use std::sync::MutexGuard;
 
 use anyhow::Result;
@@ -87,18 +89,22 @@ pub trait ComputeCmdBuffer: TransferCmdBuffer {
         where
             Self: Sized;
 
+    /// Build an acceleration structure
     fn build_acceleration_structure(self, info: &AccelerationStructureBuildInfo) -> Result<Self>
         where
             Self: Sized;
 
+    /// Build multiple acceleration structures in a single command
     fn build_acceleration_structures(self, info: &[AccelerationStructureBuildInfo]) -> Result<Self>
         where
             Self: Sized;
 
+    /// Compact an acceleration structure
     fn compact_acceleration_structure(self, src: &AccelerationStructure, dst: &AccelerationStructure) -> Result<Self>
         where
             Self: Sized;
 
+    /// Write acceleration structure properties of multiple acceleration structures in a single command.
     fn write_acceleration_structures_properties<Q: AccelerationStructurePropertyQuery>(
         self,
         src: &[AccelerationStructure],
@@ -107,6 +113,7 @@ pub trait ComputeCmdBuffer: TransferCmdBuffer {
         where
             Self: Sized;
 
+    /// Write acceleration structure properties
     fn write_acceleration_structure_properties<Q: AccelerationStructurePropertyQuery>(
         self,
         src: &AccelerationStructure,
@@ -127,8 +134,10 @@ pub trait CmdBuffer {
 
 /// Incomplete command buffer
 pub trait IncompleteCmdBuffer<'q, A: Allocator> {
+    /// The domain this command buffer operates on
     type Domain: ExecutionDomain;
 
+    /// Create a new command buffer
     fn new(
         device: Device,
         queue_lock: MutexGuard<'q, Queue>,
@@ -139,6 +148,8 @@ pub trait IncompleteCmdBuffer<'q, A: Allocator> {
     ) -> Result<Self>
     where
         Self: Sized;
+
+    /// Finish recording to this command buffer and consume it into a completed command buffer
     fn finish(self) -> Result<CommandBuffer<Self::Domain>>;
 }
 

src/core/init.rs

@@ -8,8 +8,10 @@ use crate::{
     Allocator, AppSettings, DebugMessenger, DefaultAllocator, Device, ExecutionManager, FrameManager, PhysicalDevice, Surface, VkInstance, WindowInterface,
 };
 
+/// ZST implementing initialization without a window
 pub struct HeadlessContext;
 
+/// ZST implementing initialization with a window
 pub struct WindowedContext<W: WindowInterface> {
     _phantom: PhantomData<W>,
 }

src/lib.rs

@@ -91,6 +91,8 @@
 #![feature(min_specialization)]
 #![feature(assert_matches)]
 
+#![forbid(missing_docs)]
+
 #[macro_use]
 extern crate derivative;
 #[macro_use]

src/pipeline/pipeline_layout.rs

@@ -112,6 +112,7 @@ impl Drop for PipelineLayout {
 }
 
 impl PushConstantRange {
+    /// Convert this into a Vulkan struct
     pub fn to_vk(&self) -> vk::PushConstantRange {
         vk::PushConstantRange {
             stage_flags: self.stage_flags,

src/pipeline/raytracing.rs

@@ -10,6 +10,7 @@ use crate::pipeline::pipeline_layout::PipelineLayoutCreateInfo;
 /// An index of a shader in a shader group into the shaders array.
 #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
 pub struct ShaderIndex {
+    /// The index into the array
     pub index: u32,
 }
 

src/prelude.rs

@@ -1,3 +1,5 @@
+//! Re-exports most commonly used types in the library
+
 pub use ash::vk;
 
 pub use traits::*;
@@ -49,6 +51,7 @@ pub use crate::wsi::frame::{FrameManager, InFlightContext};
 pub use crate::wsi::surface::Surface;
 pub use crate::wsi::swapchain::Swapchain;
 
+/// Re-exports all important traits of the library
 pub mod traits {
     pub use crate::allocator::traits::*;
     pub use crate::command_buffer::traits::*;

src/resource/raytracing/geometry/instances.rs

@@ -1,3 +1,5 @@
+//! Wrappers for acceleration structure instance geometry data
+
 use anyhow::Result;
 use ash::vk;
 use ash::vk::Packed24_8;
@@ -7,11 +9,15 @@ use crate::util::address::DeviceOrHostAddressConst;
 use crate::util::to_vk::{AsVulkanType, IntoVulkanType};
 use crate::util::transform::TransformMatrix;
 
+/// Instance data in an acceleration structure
 pub struct AccelerationStructureGeometryInstancesData {
+    /// Data buffer filled with packed [`AccelerationStructureInstance`] structs.
     pub data: DeviceOrHostAddressConst,
+    /// Geometry flags
     pub flags: vk::GeometryFlagsKHR,
 }
 
+/// An instance in the acceleration structure instance buffer
 #[derive(Copy, Clone)]
 #[repr(transparent)]
 pub struct AccelerationStructureInstance(vk::AccelerationStructureInstanceKHR);
@@ -33,6 +39,7 @@ impl IntoVulkanType for AccelerationStructureGeometryInstancesData {
 
 
 impl Default for AccelerationStructureInstance {
+    /// Create a default instance in an acceleration structure
     fn default() -> Self {
         Self(vk::AccelerationStructureInstanceKHR {
             transform: TransformMatrix::default().into_vulkan(),
@@ -46,26 +53,32 @@ impl Default for AccelerationStructureInstance {
 }
 
 impl AccelerationStructureInstance {
+    /// Set the custom index of this instance. The highest 8 bits of this value are ignored, only 24 bits of
+    /// precision are supported
     pub fn custom_index(mut self, idx: u32) -> Result<Self> {
         self.0.instance_custom_index_and_mask = Packed24_8::new(idx, self.0.instance_custom_index_and_mask.high_8());
         Ok(self)
     }
 
+    /// Set the mask of this instance, used to disable specific instances when tracing
     pub fn mask(mut self, mask: u8) -> Self {
         self.0.instance_custom_index_and_mask = Packed24_8::new(self.0.instance_custom_index_and_mask.low_24(), mask);
         self
     }
 
+    /// Set the hit group offset into the shader binding table for this instance
     pub fn sbt_record_offset(mut self, offset: u32) -> Result<Self> {
         self.0.instance_shader_binding_table_record_offset_and_flags = Packed24_8::new(offset, self.0.instance_shader_binding_table_record_offset_and_flags.high_8());
         Ok(self)
     }
 
+    /// Set the instance flags
     pub fn flags(mut self, flags: vk::GeometryInstanceFlagsKHR) -> Self {
         self.0.instance_shader_binding_table_record_offset_and_flags = Packed24_8::new(self.0.instance_shader_binding_table_record_offset_and_flags.low_24(), flags.as_raw() as u8);
         self
     }
 
+    /// Set the acceleration structure this instance refers to
     pub fn acceleration_structure(mut self, accel: &AccelerationStructure, mode: AccelerationStructureBuildType) -> Result<Self> {
         match mode {
             AccelerationStructureBuildType::Host => {
@@ -82,6 +95,7 @@ impl AccelerationStructureInstance {
         Ok(self)
     }
 
+    /// Set this instance's transform matrix
     pub fn transform(mut self, transform: TransformMatrix) -> Self {
         self.0.transform = transform.into_vulkan();
         self

src/resource/raytracing/geometry/mod.rs

@@ -1,3 +1,5 @@
+//! Exposes different acceleration structure geometry types
+
 use ash::vk;
 
 pub use instances::*;
@@ -10,13 +12,21 @@ use crate::util::to_vk::{AsVulkanType, IntoVulkanType};
 pub mod triangles;
 pub mod instances;
 
+/// All information required to build the geometry of an acceleration structure
 pub struct AccelerationStructureBuildGeometryInfo<'a> {
+    /// The acceleration structure type
     pub ty: AccelerationStructureType,
+    /// Acceleration structure build flags
     pub flags: vk::BuildAccelerationStructureFlagsKHR,
+    /// The acceleration structure build mode
     pub mode: vk::BuildAccelerationStructureModeKHR,
+    /// Source acceleration structure
     pub src: Option<&'a AccelerationStructure>,
+    /// Destination acceleration structure
     pub dst: Option<&'a AccelerationStructure>,
+    /// Geometry data in this acceleration structure
     pub geometries: Vec<vk::AccelerationStructureGeometryKHR>,
+    /// Scratch data used for building
     pub scratch_data: DeviceOrHostAddress,
 }
 

src/resource/raytracing/geometry/triangles.rs

@@ -1,20 +1,32 @@
+//! Wrappers for acceleration structure triangle geometry data
+
 use ash::vk;
 
 use crate::util::address::DeviceOrHostAddressConst;
 use crate::util::to_vk::{AsVulkanType, IntoVulkanType};
 
+/// Triangle data in an acceleration structure
 pub struct AccelerationStructureGeometryTrianglesData {
+    /// The vertex format
     pub format: vk::Format,
+    /// Address of the vertex buffer
     pub vertex_data: DeviceOrHostAddressConst,
+    /// Vertex stride in the vertex buffer
     pub stride: vk::DeviceSize,
+    /// Highest index of a vertex in the vertex buffer
     pub max_vertex: u32,
+    /// Index type, or `vk::IndexType::NONE_KHR` if no index buffer is used.
     pub index_type: vk::IndexType,
+    /// Address of the index buffer, this may be null if no index buffer is used
     pub index_data: DeviceOrHostAddressConst,
+    /// Address of the buffer with transform data, this may be null
     pub transform_data: DeviceOrHostAddressConst,
+    /// Geometry flags
     pub flags: vk::GeometryFlagsKHR,
 }
 
 impl AccelerationStructureGeometryTrianglesData {
+    /// Create triangle data with default settings
     pub fn default() -> Self {
         Self {
             format: vk::Format::default(),
@@ -28,37 +40,44 @@ impl AccelerationStructureGeometryTrianglesData {
         }
     }
 
+    /// Set the vertex data format
     pub fn format(mut self, format: impl Into<vk::Format>) -> Self {
         self.format = format.into();
         self
     }
 
+    /// Set the vertex buffer addres
     pub fn vertex_data(mut self, data: impl Into<DeviceOrHostAddressConst>) -> Self {
         self.vertex_data = data.into();
         self
     }
 
+    /// Set the vertex stride
     pub fn stride(mut self, stride: impl Into<vk::DeviceSize>) -> Self {
         self.stride = stride.into();
         self
     }
 
+    /// Set the highest vertex index
     pub fn max_vertex(mut self, max_vertex: u32) -> Self {
         self.max_vertex = max_vertex;
         self
     }
 
+    /// Set the index data buffer address and its type
     pub fn index_data(mut self, ty: vk::IndexType, data: impl Into<DeviceOrHostAddressConst>) -> Self {
         self.index_type = ty;
         self.index_data = data.into();
         self
     }
 
+    /// Set the transform data address
     pub fn transform_data(mut self, data: impl Into<DeviceOrHostAddressConst>) -> Self {
         self.transform_data = data.into();
         self
     }
 
+    /// Set the geometry flags
     pub fn flags(mut self, flags: vk::GeometryFlagsKHR) -> Self {
         self.flags = flags;
         self

src/util/to_vk.rs

@@ -2,6 +2,7 @@
 
 /// Convert an object into a vulkan type
 pub trait IntoVulkanType {
+    /// Output Vulkan type
     type Output;
 
     /// Consume self and return a vulkan type
@@ -10,6 +11,7 @@ pub trait IntoVulkanType {
 
 /// Get a reference to the object, as a vulkan type
 pub trait AsVulkanType {
+    /// Output Vulkan type
     type Output;
 
     /// Return a vulkan type that lives as long as self

src/wsi/frame.rs

@@ -123,7 +123,9 @@ struct PerImage {
 /// Another way to acquire an instance of this struct is through a [`ThreadContext`](crate::ThreadContext).
 #[derive(Debug)]
 pub struct InFlightContext<'f, A: Allocator = DefaultAllocator> {
+    /// The current frame's swapchain image
     pub swapchain_image: Option<ImageView>,
+    /// The current frame's swapchain image index
     pub swapchain_image_index: Option<usize>,
     pub(crate) vertex_allocator: &'f mut ScratchAllocator<A>,
     pub(crate) index_allocator: &'f mut ScratchAllocator<A>,