Docs and cleanup comments.

Author: tychedelia

crates/processing_ffi/src/lib.rs

@@ -1902,8 +1902,7 @@ pub unsafe extern "C" fn processing_buffer_write(buf_id: u64, data: *const u8, l
     error::check(|| buffer_write(Entity::from_bits(buf_id), bytes));
 }
 
-/// Returns the byte length of a buffer, or 0 if the buffer does not exist
-/// (in which case the error is set).
+/// Returns the byte length of a buffer, or 0 if not found.
 #[unsafe(no_mangle)]
 pub extern "C" fn processing_buffer_size(buf_id: u64) -> u64 {
     error::clear_error();
@@ -1966,7 +1965,7 @@ pub unsafe extern "C" fn processing_compute_set_float(
 }
 
 /// # Safety
-/// `name` must be a valid null-terminated C string.
+/// - `name` must be non-null
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn processing_compute_set_buffer(
     compute_id: u64,

crates/processing_pyo3/src/compute.rs

@@ -140,8 +140,7 @@ impl Buffer {
     }
 
     pub fn write(&mut self, values: &Bound<'_, PyAny>) -> PyResult<()> {
-        // Bytes path skips per-element conversion — the only viable route for
-        // multi-million-element uploads.
+        // bytes path skips per-element conversion for large uploads
         if let Ok(b) = values.cast::<PyBytes>() {
             return buffer_write(self.entity, b.as_bytes().to_vec())
                 .map_err(|e| PyRuntimeError::new_err(format!("{e}")));

crates/processing_pyo3/src/lib.rs

@@ -689,9 +689,7 @@ mod mewnala {
         }
     }
 
-    // Color constructors — promoted to top-level so `from mewnala import *`
-    // exposes `hsva(...)`, `srgb(...)`, etc. directly. Living in a `color`
-    // submodule conflicted with the Processing-style `color()` function.
+    // color constructors live at module level: a `color` submodule conflicted with `color()`
 
     #[pyfunction]
     fn color_hex(s: &str) -> PyResult<PyColor> {

crates/processing_pyo3/src/material.rs

@@ -55,8 +55,7 @@ pub(crate) fn py_to_shader_value(value: &Bound<'_, PyAny>) -> PyResult<shader_va
     )))
 }
 
-/// Dispatch `albedo=` by Python type to the matching Rust setter. May swap
-/// the backing asset; all other StandardMaterial state survives.
+// dispatch `albedo=` by python type; may swap the backing asset
 fn apply_albedo(entity: Entity, value: &Bound<'_, PyAny>) -> PyResult<()> {
     if let Ok(buf) = value.extract::<PyRef<Buffer>>() {
         return material_set_albedo_buffer(entity, buf.entity)
@@ -96,8 +95,7 @@ fn apply_kwargs(entity: Entity, kwargs: &Bound<'_, PyDict>) -> PyResult<()> {
 
 #[pymethods]
 impl Material {
-    /// No args: default PBR. With `shader`: custom material. Kwargs are
-    /// applied via `set` after construction.
+    /// No args: default PBR. With `shader`: custom material. Kwargs are applied via `set`.
     #[new]
     #[pyo3(signature = (shader=None, **kwargs))]
     pub fn new(shader: Option<&Shader>, kwargs: Option<&Bound<'_, PyDict>>) -> PyResult<Self> {
@@ -114,8 +112,7 @@ impl Material {
         Ok(Self { entity })
     }
 
-    /// PBR-lit material. `albedo` accepts a `Color` or a `Buffer` (the latter
-    /// being per-particle, used with `Particles`).
+    /// PBR-lit material. `albedo` accepts a `Color` or a per-particle `Buffer`.
     #[staticmethod]
     #[pyo3(signature = (**kwargs))]
     pub fn pbr(kwargs: Option<&Bound<'_, PyDict>>) -> PyResult<Self> {
@@ -139,8 +136,7 @@ impl Material {
         Ok(Self { entity })
     }
 
-    /// Patch material properties. `albedo` may swap the backing asset between
-    /// color and buffer variants; other StandardMaterial fields are preserved.
+    /// Set material properties. `albedo` may swap the backing asset; other fields are preserved.
     #[pyo3(signature = (**kwargs))]
     pub fn set(&self, kwargs: Option<&Bound<'_, PyDict>>) -> PyResult<()> {
         let Some(kwargs) = kwargs else {

crates/processing_pyo3/src/particles.rs

@@ -97,8 +97,7 @@ impl Attribute {
 #[pyclass(unsendable)]
 pub struct Particles {
     pub(crate) entity: Entity,
-    /// Name → (entity, format) so `emit(**kwargs)` can route kwargs to the
-    /// right attribute and pack them into bytes.
+    // name → (entity, format), used by `emit(**kwargs)` to route kwargs and pack bytes
     name_to_attr: HashMap<String, (Entity, AttributeFormat)>,
 }
 
@@ -116,8 +115,7 @@ impl Particles {
 
 #[pymethods]
 impl Particles {
-    /// Pass `capacity` for empty buffers, or `geometry` to seed positions
-    /// (and matching attributes) from a source mesh. Exactly one is required.
+    /// Pass `capacity` for empty buffers, or `geometry` to seed from a source mesh.
     #[new]
     #[pyo3(signature = (capacity=None, attributes=None, geometry=None))]
     pub fn new(
@@ -161,8 +159,6 @@ impl Particles {
     }
 
     /// Backing `Buffer` for a registered attribute, or `None` if not registered.
-    /// The element type matches the attribute's format so `read()` returns
-    /// typed values.
     pub fn buffer(&self, attribute: &Attribute) -> PyResult<Option<Buffer>> {
         let buf = particles_buffer(self.entity, attribute.entity)
             .map_err(|e| PyRuntimeError::new_err(format!("{e}")))?;
@@ -177,13 +173,8 @@ impl Particles {
         Ok(buf.map(|e| Buffer::from_entity(e, Some(element_type))))
     }
 
-    /// Dispatch a compute kernel against these particles' buffers. Buffers
-    /// are auto-bound by attribute name; kwargs are forwarded to
-    /// `compute.set(...)`. For example:
-    ///
-    /// ```python
-    /// p.apply(noise, scale=0.25, strength=0.02, time=t)
-    /// ```
+    /// Dispatch a compute kernel against these particles' buffers. Buffers are
+    /// auto-bound by attribute name; kwargs are forwarded to `compute.set(...)`.
     #[pyo3(signature = (compute, **kwargs))]
     pub fn apply(
         &self,
@@ -198,12 +189,8 @@ impl Particles {
     }
 
     /// Emit `n` particles into the next ring-buffer slots. Per-attribute data
-    /// is passed as kwargs keyed by attribute name; each value is a flat list
-    /// of `n * format.float_count()` floats.
-    ///
-    /// ```python
-    /// p.emit(50, position=[x0,y0,z0, x1,y1,z1, ...], color=[r0,g0,b0,a0, ...])
-    /// ```
+    /// is a kwarg keyed by attribute name; each value is a flat list of
+    /// `n * format.float_count()` floats.
     #[pyo3(signature = (n, **kwargs))]
     pub fn emit(&self, n: u32, kwargs: Option<&Bound<'_, PyDict>>) -> PyResult<()> {
         let Some(kwargs) = kwargs else {
@@ -235,9 +222,8 @@ impl Particles {
             .map_err(|e| PyRuntimeError::new_err(format!("{e}")))
     }
 
-    /// Emit `n` particles via a GPU kernel. Buffer bindings and a
-    /// `emit_range: vec4<f32> = (base_slot, n, capacity, 0)` uniform are
-    /// auto-bound; set any other uniforms via `compute.set(...)` first.
+    /// Emit `n` particles via a GPU kernel. Auto-binds buffers and an
+    /// `emit_range: vec4<f32> = (base_slot, n, capacity, 0)` uniform.
     pub fn emit_gpu(&self, n: u32, compute: &Compute) -> PyResult<()> {
         particles_emit_gpu(self.entity, n, compute.entity)
             .map_err(|e| PyRuntimeError::new_err(format!("{e}")))
@@ -257,8 +243,7 @@ pub fn kernel_noise() -> PyResult<Compute> {
 }
 
 /// Built-in transform kernel: scale → axis-angle rotate → translate. Uniforms:
-/// `translate: vec3`, `rotation_axis: vec3`, `rotation_angle: f32`,
-/// `scale: vec3`. Identity defaults are seeded so unset uniforms are no-ops.
+/// `translate: vec3`, `rotation_axis: vec3`, `rotation_angle: f32`, `scale: vec3`.
 pub fn kernel_transform() -> PyResult<Compute> {
     let entity = particles_kernel_transform().map_err(|e| PyRuntimeError::new_err(format!("{e}")))?;
     Ok(Compute::from_entity(entity))

crates/processing_render/src/compute.rs

@@ -277,10 +277,7 @@ pub fn set_compute_property(
         .get_mut(entity)
         .map_err(|_| ProcessingError::ComputeNotFound)?;
 
-    // Resource values (buffers / textures) bind directly to top-level parameters
-    // and need a category check. Scalar / vector / matrix values may target
-    // either a top-level uniform or a nested struct field (e.g. `params.dt`),
-    // so we let `apply_reflect_field` handle the path resolution itself.
+    // resources need a category check; scalars/vectors fall through to apply_reflect_field
     match value {
         ShaderValue::Buffer(buf_entity) => {
             let category = compute

crates/processing_render/src/geometry/attribute.rs

@@ -225,13 +225,11 @@ pub struct BuiltinAttributes {
     pub normal: Entity,
     pub color: Entity,
     pub uv: Entity,
-    /// Per-instance rotation as a quaternion `(x, y, z, w)`. Field-only.
+    /// Per-instance rotation as a quaternion `(x, y, z, w)`.
     pub rotation: Entity,
-    /// Per-instance scale `(x, y, z)`. Field-only.
+    /// Per-instance scale `(x, y, z)`.
     pub scale: Entity,
-    /// Per-particle lifecycle flag: `0.0` = alive, non-zero = dead (skipped in
-    /// preprocessing). Field-only. The pack pass writes this into
-    /// `MeshCullingData::dead`.
+    /// Per-particle lifecycle flag: `0.0` = alive, non-zero = dead.
     pub dead: Entity,
 }
 

crates/processing_render/src/lib.rs

@@ -1533,10 +1533,8 @@ pub fn material_set_albedo_color(entity: Entity, color: [f32; 4]) -> error::Resu
 }
 
 /// Set the albedo source to a per-particle color buffer (`Float4` per slot,
-/// indexed by `mesh.tag`). If the material is currently plain PBR, swaps the
-/// asset to a `ParticlesMaterial` while preserving every other
-/// `StandardMaterial` field. `base_color` modulates the buffer color, so
-/// leaving it WHITE renders the buffer color verbatim.
+/// indexed by `mesh.tag`). Preserves all other `StandardMaterial` fields;
+/// `base_color` modulates the buffer color.
 pub fn material_set_albedo_buffer(
     entity: Entity,
     color_buffer_entity: Entity,
@@ -1562,7 +1560,6 @@ pub fn material_set_albedo_buffer(
             .0
             .clone();
 
-        // Already field-buffer-backed: just swap the buffer handle in place.
         if let Ok(handle) = untyped.clone().try_typed::<ParticlesMaterial>() {
             let mut mats = app.world_mut().resource_mut::<Assets<ParticlesMaterial>>();
             let mat = mats
@@ -2092,11 +2089,9 @@ pub fn particles_buffer(entity: Entity, attribute_entity: Entity) -> error::Resu
     })
 }
 
-/// GPU-driven emission. Dispatches `compute_entity` over `count` invocations
-/// to initialize the next `count` ring-buffer slots. Auto-binds attribute
-/// buffers (same convention as [`particles_apply`]) and a `vec4<f32>` uniform
-/// `emit_range = (base_slot, count, capacity, 0)` from which the kernel
-/// derives its target slot. CPU-side counterpart: [`particles_emit`].
+/// GPU-driven emission into the next `count` ring-buffer slots. Auto-binds
+/// attribute buffers (same convention as [`particles_apply`]) and an
+/// `emit_range: vec4<f32> = (base_slot, count, capacity, 0)` uniform.
 pub fn particles_emit_gpu(
     particles_entity: Entity,
     count: u32,
@@ -2241,9 +2236,7 @@ pub fn particles_kernel_noise() -> error::Result<Entity> {
 
 /// Built-in transform kernel: scale → axis-angle rotate → translate on
 /// `position`. Uniforms: `translate: vec3`, `rotation_axis: vec3`,
-/// `rotation_angle: f32`, `scale: vec3`. Identity defaults are seeded so
-/// any unset parameter behaves as a no-op (without them, default-zero
-/// `scale` would collapse the field to the origin on the first dispatch).
+/// `rotation_angle: f32`, `scale: vec3`. Identity defaults are seeded.
 pub fn particles_kernel_transform() -> error::Result<Entity> {
     let shader = shader_load(particles::kernels::TRANSFORM_PATH)?;
     let entity = compute_create(shader)?;

crates/processing_render/src/material/custom.rs

@@ -181,9 +181,7 @@ pub fn load_shader(In(path): In<String>, world: &mut World) -> Result<Entity> {
     };
     use bevy::ecs::system::RunSystemOnce;
 
-    // URL-scheme paths (e.g. `embedded://crate/file.wgsl`) parse as-is — they
-    // already specify their asset source. Otherwise treat as a relative path
-    // and fall through to the configured asset directory if any.
+    // url-scheme paths parse as-is; others go through the configured asset dir
     let asset_path: AssetPath = if path.contains("://") {
         AssetPath::parse(&path).into_owned()
     } else {

crates/processing_render/src/particles/kernels/noise.wgsl

@@ -1,5 +1,3 @@
-// Per-particle position displacement by sampled 3D value noise.
-
 struct Params {
     scale: f32,
     strength: f32,