docs: document the local: bool parameter across bake and resolution APIs

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<D: Deref<Target = MultipartDocument>>(
     document: D,
     resolutions: &ResolutionResult,
@@ -957,6 +976,12 @@ pub fn bake_part_from_multipart_document<D: Deref<Target = MultipartDocument>>(
     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,

ldraw/src/library.rs

@@ -40,6 +40,12 @@ pub trait DocumentLoader<T> {
 pub trait LibraryLoader {
     async fn load_colors(&self) -> Result<ColorCatalog, ResolutionError>;
 
+    /// 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<MultipartDocument>, bool)> {
         if local {
             let local_entry = self.local_entries.get(alias);