docs: add public docs

src/main.rs

@@ -1,3 +1,15 @@
+#![deny(missing_docs)]
+//! wgpu-openxr-example is a barebones example of how to integrate OpenXR with wgpu (Vulkan-only).
+//!
+//! It has four modes:
+//!   - cargo run --no-default-features: desktop-only, renders the scene without *any* XR integration
+//!   - cargo run -- desktop: build with XR support, but render the scene without initialising XR
+//!   - cargo run -- desktop-with-xr-resolution: build with XR support, initialise XR, but do not render to headset
+//!   - cargo run -- xr: build with XR support, and render to the headset
+//!
+//! These modes are intended to show you how to gracefully integrate XR into your project's code
+//! and how you can move from one stage of integration to the next.
+
 use std::path::Path;
 
 use anyhow::Context;
@@ -25,7 +37,8 @@ use main_state::{Instance, MainState};
 use texture::Texture;
 use types::*;
 
-#[allow(dead_code)]
+/// Encapsulates all wgpu device-related state. Used to isolate XR initialisation
+/// from desktop initialisation.
 pub struct WgpuState {
     instance: wgpu::Instance,
     adapter: wgpu::Adapter,

src/wgsl.rs

@@ -1,10 +1,15 @@
+//! Implements a very simple preprocessor to embed other WGSL files.
+
 use std::{
     collections::HashMap,
     path::{Path, PathBuf},
 };
 
 use anyhow::Context;
 
+/// Preprocesses the given `current_file` within the `files`, and returns the preprocessed file.
+/// `files` must contain non-preprocessed files.
+///
 /// This is _not_ a robust preprocessor. It's the bare minimum to make this example work.
 /// This *will* fall down at the first hurdle.
 pub fn preprocess(files: &HashMap<PathBuf, String>, current_file: &str) -> anyhow::Result<String> {
@@ -25,10 +30,12 @@ pub fn preprocess(files: &HashMap<PathBuf, String>, current_file: &str) -> anyho
     Ok(current_file)
 }
 
+/// A helper for [preprocess] that wraps it with some files to use for state.
 pub struct Preprocessor {
     files: HashMap<PathBuf, String>,
 }
 impl Preprocessor {
+    /// Create a [Preprocessor] from the given `path`.
     pub fn from_directory(path: &Path) -> std::io::Result<Self> {
         Ok(Self {
             files: std::fs::read_dir(path)?
@@ -49,12 +56,14 @@ impl Preprocessor {
         })
     }
 
+    /// Runs [crate::preprocess] on the given `filename`, assuming that it is within the files that
+    /// initialized this preprocessor.
     pub fn preprocess(&self, filename: impl AsRef<Path>) -> anyhow::Result<String> {
         preprocess(
             &self.files,
             self.files
                 .get(filename.as_ref())
-                .context("File not present!")?
+                .context("file not present")?
                 .as_str(),
         )
     }