docs(tvix/[ca]store): improve docstrings, remove wildcard imports r/8901

Extend the docstrings of `add_default_services`, and add one for
`addrs_to_configs` as well as the module-wide one at
`tvix_store::composition`.

Change-Id: Ie9b449988eb210cd65b19b174094bbe0c4af2fd6
Reviewed-on: https://cl.tvl.fyi/c/depot/+/12748
Tested-by: BuildkiteCI
Reviewed-by: yuka <yuka@yuka.dev>

4 files changed, 31 insertions, 14 deletions

diff --git a/tvix/castore/src/composition.rs b/tvix/castore/src/composition.rs
index c3b6222d5d86..e997152d60be 100644
--- a/tvix/castore/src/composition.rs
+++ b/tvix/castore/src/composition.rs
@@ -270,9 +270,10 @@ pub static REG: LazyLock<&'static Registry> = LazyLock::new(|| {
 
 // ---------- End of generic registry code --------- //
 
-/// Register the builtin services of tvix_castore with the given registry.
-/// This is useful for creating your own registry with the builtin types _and_
-/// extra third party types.
+/// Register the builtin services of tvix_castore (blob services and directory
+/// services) with the given registry.
+/// This can be used outside to create your own registry with the builtin types
+/// _and_ extra third party types.
 pub fn add_default_services(reg: &mut Registry) {
     crate::blobservice::register_blob_services(reg);
     crate::directoryservice::register_directory_services(reg);
diff --git a/tvix/store/src/composition.rs b/tvix/store/src/composition.rs
index 063236136fd1..ce35cc2fcac2 100644
--- a/tvix/store/src/composition.rs
+++ b/tvix/store/src/composition.rs
@@ -1,6 +1,13 @@
+//! This module provides a registry knowing about {Blob,Directory,PathInfo}
+//! Services, as well as the [add_default_services] helper to seed new
+//! registries with everything known here.
+//! The composition machinery itself is defined in
+//! [tvix_castore::composition], which works generically with different kinds
+//! of services.
+
 use std::sync::LazyLock;
 
-pub use tvix_castore::composition::*;
+use tvix_castore::composition::Registry;
 
 /// The provided registry of tvix_store, which has all the builtin
 /// tvix_castore (BlobStore/DirectoryStore) and tvix_store
@@ -12,9 +19,11 @@ pub static REG: LazyLock<&'static Registry> = LazyLock::new(|| {
     Box::leak(Box::new(reg))
 });
 
-/// Register the builtin services of tvix_castore and tvix_store with the given
-/// registry. This is useful for creating your own registry with the builtin
-/// types _and_ extra third party types.
+/// Register the builtin services of tvix_castore (blob services and directory
+/// services), as well as the ones from tvix_store (PathInfo service) with the
+/// given registry.
+/// This can be used outside to create your own registry with the builtin types
+/// _and_ extra third party types.
 pub fn add_default_services(reg: &mut Registry) {
     tvix_castore::composition::add_default_services(reg);
     crate::pathinfoservice::register_pathinfo_services(reg);
diff --git a/tvix/store/src/pathinfoservice/from_addr.rs b/tvix/store/src/pathinfoservice/from_addr.rs
index 2f5c776293cb..0e8cc064dc9e 100644
--- a/tvix/store/src/pathinfoservice/from_addr.rs
+++ b/tvix/store/src/pathinfoservice/from_addr.rs
@@ -1,9 +1,10 @@
 use super::PathInfoService;
 
-use crate::composition::{
-    with_registry, CompositionContext, DeserializeWithRegistry, ServiceBuilder, REG,
-};
+use crate::composition::REG;
 use std::sync::Arc;
+use tvix_castore::composition::{
+    with_registry, CompositionContext, DeserializeWithRegistry, ServiceBuilder,
+};
 use tvix_castore::Error;
 use url::Url;
 
@@ -56,11 +57,12 @@ pub async fn from_addr(
 #[cfg(test)]
 mod tests {
     use super::from_addr;
-    use crate::composition::{Composition, DeserializeWithRegistry, ServiceBuilder, REG};
+    use crate::composition::REG;
     use rstest::rstest;
     use std::sync::LazyLock;
     use tempfile::TempDir;
     use tvix_castore::blobservice::{BlobService, MemoryBlobServiceConfig};
+    use tvix_castore::composition::{Composition, DeserializeWithRegistry, ServiceBuilder};
     use tvix_castore::directoryservice::{DirectoryService, MemoryDirectoryServiceConfig};
 
     static TMPDIR_REDB_1: LazyLock<TempDir> = LazyLock::new(|| TempDir::new().unwrap());
diff --git a/tvix/store/src/utils.rs b/tvix/store/src/utils.rs
index 0a1888f6f2e1..19e0dce568ce 100644
--- a/tvix/store/src/utils.rs
+++ b/tvix/store/src/utils.rs
@@ -9,11 +9,12 @@ use tokio::io::{self, AsyncWrite};
 use tvix_castore::{blobservice::BlobService, directoryservice::DirectoryService};
 use url::Url;
 
-use crate::composition::{
-    with_registry, Composition, DeserializeWithRegistry, ServiceBuilder, REG,
-};
+use crate::composition::REG;
 use crate::nar::{NarCalculationService, SimpleRenderer};
 use crate::pathinfoservice::PathInfoService;
+use tvix_castore::composition::{
+    with_registry, Composition, DeserializeWithRegistry, ServiceBuilder,
+};
 
 #[derive(serde::Deserialize, Default)]
 pub struct CompositionConfigs {
@@ -127,6 +128,10 @@ impl From<ServiceUrlsMemory> for ServiceUrls {
     }
 }
 
+/// Deserializes service addresses into composition config, configuring each
+/// service as the single "root".
+/// If the `xp-composition-cli` feature is enabled, and a file specified in the
+/// `--experimental-store-composition` parameter, this is used instead.
 pub async fn addrs_to_configs(
     urls: impl Into<ServiceUrls>,
 ) -> Result<CompositionConfigs, Box<dyn std::error::Error + Send + Sync>> {