Reattach docs to the items they describe

node-graph/libraries/core-types/src/record/input.rs

@@ -207,8 +207,6 @@ impl<'a, 'e, N> RecordInput<'a, 'e, N> {
 	}
 }
 
-/// The raw lazy input handed to a poll kernel whose input rides records while
-/// the kernel consumes the plain element.
 /// # Safety
 /// `rec` must be a record of the layout the offsets were resolved against
 /// and `El` its element type; both are proven at wiring.
@@ -216,6 +214,8 @@ unsafe fn element_only<El: Clone>(rec: Rec<'_>, _reads: &[Option<usize>]) -> El
 	unsafe { read_element::<El>(rec) }
 }
 
+/// The raw lazy input handed to a poll kernel whose input rides records while
+/// the kernel consumes the plain element.
 pub struct ElementInput<'a, 'e, Out, N> {
 	node: &'a N,
 	layout: &'a Layout,

node-graph/libraries/core-types/src/record/layout.rs

@@ -334,7 +334,6 @@ pub fn empty_layout() -> &'static Layout {
 	EMPTY.get_or_init(Layout::default)
 }
 
-/// Declarative record-io metadata for a node type, emitted by the macro into
 /// A record node's output layout with the frame size and carrier copy plan derived from it.
 #[derive(Clone, Debug, Default)]
 pub struct RecordLayout {
@@ -347,6 +346,7 @@ pub struct RecordLayout {
 	pub lane_invariant: u32,
 }
 
+/// Declarative record-io metadata for a node type, emitted by the macro into
 /// its registry entry so the compiler can fold each input's layout without
 /// running the node's constructor. [`fold`](LayoutMeta::fold) reproduces the
 /// layout the constructor derives at wiring today; the compiler layout pass
@@ -436,13 +436,13 @@ impl LayoutMeta {
 		let layout = self.fold(inputs);
 		let frame_bytes = layout.frame_bytes();
 		let plan = match self.sources.first() {
-			// A reducer collapses its carrier's levels, so it writes a fresh record rather than copying fields down.
 			Some(&source) if self.level_delta >= 0 => {
 				let from = inputs[source as usize].expect("layout resolve source input has no layout");
 				let carry_element = matches!(self.element, ElementSpec::Carried);
 				let removes: Vec<(&str, u8)> = self.removes.clone();
 				copy_plan(from, &layout, carry_element, &removes)
 			}
+			// A reducer collapses its carrier's levels, so it writes a fresh record rather than copying fields down.
 			_ => Vec::new(),
 		};
 		RecordLayout {

node-graph/libraries/core-types/src/registry.rs

@@ -143,9 +143,6 @@ impl<Input, N> Node<Input> for SharedSource<N>
 where
 	N: Node<Input> + ?Sized,
 {
-	/// A node takes exactly its own frame out of its caller's free space: the
-	/// caller minted the claim and kept the cursor, so the frame accounting is
-	/// structural here and asserted where a claim is split.
 	fn serve<'e, 'l>(&self, input: &Input, slot: crate::record::FrameClaim<'e, 'l>) -> crate::gpoll::GPoll<crate::record::Served<'e>>
 	where
 		Input: crate::context::ExtractArena<ArenaRef = &'e crate::arena::Arena>,

node-graph/node-macro/src/codegen/classify.rs

@@ -423,10 +423,7 @@ pub(crate) fn flip_carrier(parsed: &ParsedNodeFn) -> bool {
 	!(async_kernel && lend.is_some())
 }
 
-/// Whether a plain node's lowering flips onto record inputs: sync,
+/// Whether any value input declares `IList` nesting, so the node materializes a ranked input.
-/// fully-concrete value-input nodes in this cut; batch, shader, async, lend,
-/// lazy, and generic nodes keep the plain lowering until their record forms
-/// land.
 pub(crate) fn has_materialized_input(parsed: &ParsedNodeFn) -> bool {
 	parsed
 		.fields
@@ -434,6 +431,7 @@ pub(crate) fn has_materialized_input(parsed: &ParsedNodeFn) -> bool {
 		.any(|field| matches!(&field.ty, ParsedFieldType::Regular(RegularParsedField { list_levels, .. }) if *list_levels > 0))
 }
 
+/// Whether a plain node's lowering flips onto record inputs.
 pub(crate) fn record_flip(parsed: &ParsedNodeFn) -> bool {
 	if record_shape(parsed).is_some() || has_record_io(parsed) || routing_io(parsed).is_some() || record_opaque(parsed) {
 		return false;

node-graph/node-macro/src/parsing.rs

@@ -619,10 +619,10 @@ impl Parse for NodeFnAttributes {
 					let parsed_path: Path = meta.parse_args().map_err(|_| Error::new_spanned(meta, "Expected a valid path for 'batch', e.g., batch(my_batch)"))?;
 					batch = Some(parsed_path);
 				}
-				// Instructs the generated eval to report `Pending` instead of passing partial upstream values into this node.
+				// Keeps the plain-input lowering for this node during the record transition.
 				//
 				// Example usage:
-				// #[node_macro::node(..., no_partial, ...)]
+				// #[node_macro::node(..., plain, ...)]
 				"plain" => {
 					let path = meta.require_path_only()?;
 					if plain {
@@ -630,6 +630,10 @@ impl Parse for NodeFnAttributes {
 					}
 					plain = true;
 				}
+				// Instructs the generated eval to report `Pending` instead of passing partial upstream values into this node.
+				//
+				// Example usage:
+				// #[node_macro::node(..., no_partial, ...)]
 				"no_partial" => {
 					let path = meta.require_path_only()?;
 					if no_partial {