From 0c5ffb0efae8a287de82e8cebf5eb159611342b1 Mon Sep 17 00:00:00 2001 From: Brian Karfunkel <1545637+bkfunk@users.noreply.github.com> Date: Wed, 13 May 2026 12:22:53 -0400 Subject: [PATCH] docs: document the `local: bool` parameter on bake and resolution APIs The `local: bool` flag threads through `LibraryLoader::load_ref`, `ResolutionResult::query`, and `bake_part_from_*`, but its meaning was nowhere stated. Callers reading from one site couldn't tell whether the flag had the same semantics at the next site, and the bake-time flag silently has to match the resolution-time flag. Adds doc comments at the four sites that take `local: bool` explaining that it distinguishes user-supplied / working-directory parts (`true`) from stock library parts (`false`), and noting that the bake-time value must match the resolution-time value. Co-Authored-By: Claude Opus 4.7 (1M context) --- ir/src/part.rs | 25 +++++++++++++++++++++++++ ldraw/src/library.rs | 14 ++++++++++++++ 2 files changed, 39 insertions(+) diff --git a/ir/src/part.rs b/ir/src/part.rs index 97488ed..fde849a 100644 --- a/ir/src/part.rs +++ b/ir/src/part.rs @@ -939,6 +939,25 @@ impl<'a> PartBaker<'a> { } } +/// Builds a baked [`Part`] from a [`MultipartDocument`] using previously-resolved +/// sub-parts. +/// +/// The `local` flag controls how sub-part references inside the document are +/// resolved against `resolutions`, and must match the `local` value that was +/// passed to [`LibraryLoader::load_ref`] / [`ResolutionResult::query`] when the +/// document and its dependencies were loaded: +/// +/// - `local = true`: this is a user-supplied / working-directory document. +/// Sub-part references resolve against local entries first, then fall back +/// to the stock library. +/// - `local = false`: this is a stock library part. Sub-part references +/// resolve only against library entries. +/// +/// Passing the wrong value can produce a part with missing or incorrect +/// sub-geometry; it is not validated. +/// +/// [`LibraryLoader::load_ref`]: ldraw::library::LibraryLoader::load_ref +/// [`ResolutionResult::query`]: ldraw::library::ResolutionResult::query pub fn bake_part_from_multipart_document>( document: D, resolutions: &ResolutionResult, @@ -957,6 +976,12 @@ pub fn bake_part_from_multipart_document>( baker.bake() } +/// Builds a baked [`Part`] from a single-page [`Document`] using +/// previously-resolved sub-parts. +/// +/// See [`bake_part_from_multipart_document`] for the semantics of `local`; the +/// same value must be passed here as was used when resolving the document's +/// dependencies. pub fn bake_part_from_document( document: &Document, resolutions: &ResolutionResult, diff --git a/ldraw/src/library.rs b/ldraw/src/library.rs index f60489c..1b8dedf 100644 --- a/ldraw/src/library.rs +++ b/ldraw/src/library.rs @@ -40,6 +40,12 @@ pub trait DocumentLoader { pub trait LibraryLoader { async fn load_colors(&self) -> Result; + /// Loads the document for `alias`. + /// + /// `local = true` indicates the alias is a user-supplied / working-directory + /// part: the loader should look in any caller-provided local roots before + /// falling back to the stock library. `local = false` restricts the search + /// to the stock library only. async fn load_ref( &self, alias: PartAlias, @@ -363,6 +369,14 @@ impl ResolutionResult { Self::default() } + /// Looks up the resolved document for `alias`. + /// + /// When `local = true`, local entries are preferred over library entries + /// (with the same fallback behavior as [`LibraryLoader::load_ref`]). When + /// `local = false`, only the library entries are searched. + /// + /// The returned `bool` indicates whether the hit came from local entries + /// (`true`) or library entries (`false`). pub fn query(&self, alias: &PartAlias, local: bool) -> Option<(Arc, bool)> { if local { let local_entry = self.local_entries.get(alias);