refactor(tvix/eval): prefix ctx iterators in NixString

NixString::iter_plain() didn't make much sense, especially without a docstring.

Rename it to iter_ctx_plain(), and copy the docstring from NixContext.

Do the same for the two other context element types too.

Change-Id: I1bbfcb967d8d9b14487d069bfe3a1f762253ef4d
Reviewed-on: https://cl.tvl.fyi/c/depot/+/11882
Tested-by: BuildkiteCI
Reviewed-by: Ilan Joselevich <personal@ilanjoselevich.com>
Reviewed-by: flokli <flokli@flokli.de>

tvix/eval/src/value/string.rs

@@ -767,21 +767,33 @@ impl NixString {
         context
     }
 
+    /// Iterates over all context elements.
+    /// See [iter_plain], [iter_derivation], [iter_single_outputs].
     pub fn iter_context(&self) -> impl Iterator<Item = &NixContext> {
         self.context().into_iter()
     }
 
-    pub fn iter_plain(&self) -> impl Iterator<Item = &str> {
+    /// Iterates over "plain" context elements, e.g. sources imported
+    /// in the store without more information, i.e. `toFile` or coerced imported paths.
+    /// It yields paths to the store.
+    pub fn iter_ctx_plain(&self) -> impl Iterator<Item = &str> {
         self.iter_context().flat_map(|context| context.iter_plain())
     }
 
-    pub fn iter_derivation(&self) -> impl Iterator<Item = &str> {
+    /// Iterates over "full derivations" context elements, e.g. something
+    /// referring to their `drvPath`, i.e. their full sources and binary closure.
+    /// It yields derivation paths.
+    pub fn iter_ctx_derivation(&self) -> impl Iterator<Item = &str> {
         return self
             .iter_context()
             .flat_map(|context| context.iter_derivation());
     }
 
-    pub fn iter_single_outputs(&self) -> impl Iterator<Item = (&str, &str)> {
+    /// Iterates over "single" context elements, e.g. single derived paths,
+    /// or also known as the single output of a given derivation.
+    /// The first element of the tuple is the output name
+    /// and the second element is the derivation path.
+    pub fn iter_ctx_single_outputs(&self) -> impl Iterator<Item = (&str, &str)> {
         return self
             .iter_context()
             .flat_map(|context| context.iter_single_outputs());

tvix/glue/src/builtins/derivation.rs

@@ -554,7 +554,9 @@ pub(crate) mod derivation_builtins {
             .to_contextful_str()
             .context("evaluating the `content` parameter of builtins.toFile")?;
 
-        if content.iter_derivation().count() > 0 || content.iter_single_outputs().count() > 0 {
+        if content.iter_ctx_derivation().count() > 0
+            || content.iter_ctx_single_outputs().count() > 0
+        {
             return Err(ErrorKind::UnexpectedContext);
         }
 
@@ -568,13 +570,14 @@ pub(crate) mod derivation_builtins {
             let blob_digest = blob_writer.close().await?;
             let ca_hash = CAHash::Text(Sha256::digest(&content).into());
 
-            let store_path = build_ca_path(name.to_str()?, &ca_hash, content.iter_plain(), false)
+            let store_path =
-                .map_err(|_e| {
+                build_ca_path(name.to_str()?, &ca_hash, content.iter_ctx_plain(), false)
-                    nix_compat::derivation::DerivationError::InvalidOutputName(
+                    .map_err(|_e| {
-                        name.to_str_lossy().into_owned(),
+                        nix_compat::derivation::DerivationError::InvalidOutputName(
-                    )
+                            name.to_str_lossy().into_owned(),
-                })
+                        )
-                .map_err(DerivationError::InvalidDerivation)?;
+                    })
+                    .map_err(DerivationError::InvalidDerivation)?;
 
             let root_node = Node::File(FileNode {
                 name: store_path.to_string().into(),
@@ -592,7 +595,7 @@ pub(crate) mod derivation_builtins {
 
             // assemble references from plain context.
             let reference_paths: Vec<StorePathRef> = content
-                .iter_plain()
+                .iter_ctx_plain()
                 .map(|elem| StorePathRef::from_absolute_path(elem.as_bytes()))
                 .collect::<Result<_, _>>()
                 .map_err(|e| ErrorKind::TvixError(Rc::new(e)))?;