doc: improve docs

spirv-cross2/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "spirv-cross2"
-version = "0.4.0"
+version = "0.4.1"
 edition = "2021"
 
 license = "MIT OR Apache-2.0"

spirv-cross2/src/handle.rs

@@ -144,7 +144,7 @@ impl<T> Compiler<T> {
         handle.tag == PointerOnlyForComparison(self.ptr)
     }
 
-    /// Yield the value of the handle, if it originated from the same context,
+    /// Yield the value of the handle, if it originated from the same compiler instance,
     /// otherwise return [`SpirvCrossError::InvalidHandle`].
     pub fn yield_id<I: Id>(&self, handle: Handle<I>) -> error::Result<I> {
         if self.handle_is_valid(&handle) {

spirv-cross2/src/lib.rs

@@ -23,12 +23,10 @@
 //! can be coerced automatically to [`CompilerStr`] as an input, and [`CompilerStr`] can easily be copied
 //! to a Rust string type.
 //!
-//! If a returned [`CompilerStr`] is owned by the context and is immutable,
-//! it will share the lifetime of the context. Some functions return _short lived_ strings which
-//! are owned by the compiler instance, rather than the context.
+//! If a returned [`CompilerStr`] is backed by immutable memory, it will have a `'static` lifetime.
 //!
-//! The underlying string data could possibly be modified by `set_` functions,
-//! thus they only have a lifetime corresponding to the lifetime of the immutable borrow of the [`Compiler`]
+//! If instead the underlying string data could possibly be modified by `set_` functions,
+//! they will only have a lifetime corresponding to the lifetime of the immutable borrow of the [`Compiler`]
 //! that produced them. References to these short-lived strings can not be alive before calling a
 //! mutating function.
 //!
@@ -37,7 +35,7 @@
 //! and the pointer will be passed directly back. Rust [`&CStr`](std::ffi::CStr) will not reallocate.
 //!
 //! If you are just passing in a string constant using a [C-string literal](https://doc.rust-lang.org/edition-guide/rust-2021/c-string-literals.html)
-//! will be the most efficient. Otherwise it is always better to work with Rust [`String`] and [`&str`](str),
+//! will be the most efficient. Otherwise, it is always better to work with Rust [`String`] and [`&str`](str),
 //! if you are dynamically building up a string. In particular, [`String`] will not reallocate if
 //! there is enough capacity to append a nul byte before being passed to FFI.
 //!
@@ -53,14 +51,6 @@
 //! Handles can be unsafely forged with [`Compiler::create_handle`], but there are very few if any
 //! situations where this would be needed.
 //!
-//! ## Context
-//! The SPIRV-Cross API puts all allocations behind a context object, which is encapsulated
-//! within [`Compiler`]. All allocations originating from this context are refcounted, and
-//! will have `'static` lifetime, and are immutable once created.
-//!
-//! Some allocations are made directly in the SPIRV-Cross compiler object. Such allocations
-//! can only live for as long as the borrow to [`Compiler`].
-//!
 //! ## Features
 //! By default, the `glsl`, `hlsl`, and `msl` features are enabled by default. The `cpp` and `json` targets can be enabled
 //! in Cargo.toml

spirv-cross2/src/reflect/buffers.rs

@@ -38,8 +38,8 @@ impl<T> Compiler<T> {
     /// Queries if a buffer object has a neighbor "counter" buffer.
     /// If so, the ID of that counter buffer will be returned.
     ///
-    /// If SPV_GOOGLE_hlsl_functionality1 is used, this can be used even with a stripped SPIR-V module.
-    /// Otherwise, this query is purely based on OpName identifiers as found in the SPIR-V module, and will
+    /// If `SPV_GOOGLE_hlsl_functionality` is used, this can be used even with a stripped SPIR-V module.
+    /// Otherwise, this query is purely based on `OpName` identifiers as found in the SPIR-V module, and will
     /// only return true if OpSource was reported HLSL.
     /// To rely on this functionality, ensure that the SPIR-V module is not stripped.
     pub fn hlsl_counter_buffer(

spirv-cross2/src/reflect/constants.rs

@@ -227,8 +227,9 @@ impl<T> Compiler<T> {
     /// the LocalSize execution mode is ignored.
     ///
     /// This constant vector can be a constant vector, specialization constant vector, or partly specialized constant vector.
-    /// To modify and query work group dimensions which are specialization constants, SPIRConstant values must be modified
-    /// directly via get_constant() rather than using LocalSize directly. This function will return which constants should be modified.
+    /// To modify and query work group dimensions which are specialization constants, constant values must be modified
+    /// directly via [`Compiler::set_specialization_constant_value`] rather than using LocalSize directly.
+    /// This function will return which constants should be modified.
     ///
     /// To modify dimensions which are *not* specialization constants, set_execution_mode should be used directly.
     /// Arguments to set_execution_mode which are specialization constants are effectively ignored during compilation.

spirv-cross2/src/string.rs

@@ -10,7 +10,7 @@ use std::ops::Deref;
 ///
 /// In most cases, users of this library do not need to worry about
 /// constructing a [`CompilerStr`]. All functions that take strings
-/// take `impl Into<ContextStr<'_>>`, which converts automatically from
+/// take `impl Into<CompilerStr<'_>>`, which converts automatically from
 /// [`&str`](str) and [`String`](String).
 ///
 /// [`CompilerStr`] also implements [`Deref`](Deref) for [`&str`](str),