From 08ca2963c5e1a7da579f080ea41e6598e374f640 Mon Sep 17 00:00:00 2001
From: chyyran <ronny@ronnychan.ca>
Date: Thu, 19 Jan 2023 18:59:39 -0500
Subject: [PATCH] doc: document reflect module

---
 librashader-reflect/src/lib.rs | 46 ++++++++++++++++++++++++++++++++++
 librashader/src/lib.rs         | 45 ++++++++++++++++++++++++++++++++-
 2 files changed, 90 insertions(+), 1 deletion(-)

diff --git a/librashader-reflect/src/lib.rs b/librashader-reflect/src/lib.rs
index df1a583..eeedef0 100644
--- a/librashader-reflect/src/lib.rs
+++ b/librashader-reflect/src/lib.rs
@@ -1,4 +1,50 @@
 //! Shader reflection and cross-compilation for librashader.
+//!
+//! ## Usage
+//!
+//! librashader-reflect requires the `type_alias_impl_trait` nightly feature. You should choose your
+//! target shading language, and a compilation type.
+//!
+//! ```rust
+//! #![feature(type_alias_impl_trait)]
+//!
+//! use std::error::Error;
+//! use librashader_preprocess::ShaderSource;
+//! use librashader_presets::ShaderPreset;
+//! use librashader_reflect::back::{CompileReflectShader, FromCompilation};
+//! use librashader_reflect::back::targets::SPIRV;
+//! use librashader_reflect::front::GlslangCompilation;
+//! use librashader_reflect::reflect::presets::{CompilePresetTarget, ShaderPassArtifact};
+//! use librashader_reflect::reflect::semantics::ShaderSemantics;
+//! type Artifact = impl CompileReflectShader<SPIRV, GlslangCompilation>;
+//! type ShaderPassMeta = ShaderPassArtifact<Artifact>;
+//!
+//! // Compile single shader
+//! pub fn compile_spirv(
+//!         source: &ShaderSource,
+//!     ) -> Result<Artifact, Box<dyn Error>>
+//! {
+//!     let compilation = GlslangCompilation::compile(&source)?;
+//!     let spirv = SPIRV::from_compilation(artifact)?;
+//!     Ok(spirv)
+//! }
+//!
+//! // Compile preset
+//! pub fn compile_preset(preset: ShaderPreset) -> Result<(Vec<ShaderPassMeta>, ShaderSemantics), Box<dyn Error>>
+//! {
+//!     let (passes, semantics) = SPIRV::compile_preset_passes::<GlslangCompilation, Box<dyn Error>>(
+//!     preset.shaders, &preset.textures)?;
+//!     Ok((passes, semantics))
+//! }
+//! ```
+//!
+//! ## What's with all the traits?
+//! librashader-reflect is designed to be compiler-agnostic. In the future, we will allow usage of
+//! [naga](https://docs.rs/naga/latest/naga/index.html), a pure-Rust shader compiler, when it has
+//! matured enough to support [the features librashader needs](https://github.com/gfx-rs/naga/issues/1012).
+//!
+//! In the meanwhile, the only supported compilation type is [GlslangCompilation](crate::front::GlslangCompilation),
+//! which does transpilation via [shaderc](https://github.com/google/shaderc) and [SPIRV-Cross](https://github.com/KhronosGroup/SPIRV-Cross).
 #![feature(type_alias_impl_trait)]
 
 /// Shader codegen backends.
diff --git a/librashader/src/lib.rs b/librashader/src/lib.rs
index afc87ff..1c5b6b8 100644
--- a/librashader/src/lib.rs
+++ b/librashader/src/lib.rs
@@ -75,7 +75,50 @@ pub mod preprocess {
 
 #[cfg(feature = "reflect")]
 #[doc(cfg(reflect))]
-/// Shader compilation and reflection.
+/// Shader reflection and cross-compilation.
+///
+/// The `type_alias_impl_trait` nightly feature is required. You should choose your
+/// target shading language, and a compilation type.
+///
+/// ```rust
+/// #![feature(type_alias_impl_trait)]
+///
+/// use std::error::Error;
+/// use librashader::preprocess::ShaderSource;
+/// use librashader::presets::ShaderPreset;
+/// use librashader::reflect::{CompileReflectShader, FromCompilation, CompilePresetTarget, ShaderPassArtifact};
+/// use librashader::reflect::targets::SPIRV;
+/// use librashader::reflect::cross::GlslangCompilation;
+/// use librashader::reflect::semantics::ShaderSemantics;
+/// type Artifact = impl CompileReflectShader<SPIRV, GlslangCompilation>;
+/// type ShaderPassMeta = ShaderPassArtifact<Artifact>;
+///
+/// // Compile single shader
+/// pub fn compile_spirv(
+///         source: &ShaderSource,
+///     ) -> Result<Artifact, Box<dyn Error>>
+/// {
+///     let compilation = GlslangCompilation::compile(&source)?;
+///     let spirv = SPIRV::from_compilation(artifact)?;
+///     Ok(spirv)
+/// }
+///
+/// // Compile preset
+/// pub fn compile_preset(preset: ShaderPreset) -> Result<(Vec<ShaderPassMeta>, ShaderSemantics), Box<dyn Error>>
+/// {
+///     let (passes, semantics) = SPIRV::compile_preset_passes::<GlslangCompilation, Box<dyn Error>>(
+///     preset.shaders, &preset.textures)?;
+///     Ok((passes, semantics))
+/// }
+/// ```
+///
+/// ## What's with all the traits?
+/// librashader-reflect is designed to be compiler-agnostic. In the future, we will allow usage of
+/// [naga](https://docs.rs/naga/latest/naga/index.html), a pure-Rust shader compiler, when it has
+/// matured enough to support [the features librashader needs](https://github.com/gfx-rs/naga/issues/1012).
+///
+/// In the meanwhile, the only supported compilation type is [GlslangCompilation](crate::front::GlslangCompilation),
+/// which does transpilation via [shaderc](https://github.com/google/shaderc) and [SPIRV-Cross](https://github.com/KhronosGroup/SPIRV-Cross).
 pub mod reflect {
     /// Supported shader compiler targets.
     pub mod targets {