Skip to content

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

Open
bkfunk wants to merge 1 commit into
segfault87:mainfrom
bkfunk:docs/local-bool-param
Open

docs: document the local: bool parameter across bake and resolution APIs#69
bkfunk wants to merge 1 commit into
segfault87:mainfrom
bkfunk:docs/local-bool-param

Conversation

@bkfunk
Copy link
Copy Markdown

@bkfunk bkfunk commented May 13, 2026

Summary

The local: bool flag threads through several entry points but has no doc comment anywhere:

  • LibraryLoader::load_ref
  • ResolutionResult::query
  • bake_part_from_multipart_document
  • bake_part_from_document

A reader at any one of those sites can't tell whether the flag has consistent semantics across them, or that the bake-time value silently has to match the resolution-time value. Callers (including in-tree tools and downstream consumers) tend to pass `false` by convention rather than understanding.

Change

Adds doc comments at the four sites explaining:

  • `local = true`: this is a user-supplied / working-directory part. 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 against library entries only.
  • The bake-time value must match the value passed at resolution time; mismatches are not validated and may produce parts with missing or incorrect sub-geometry.

No code changes — only doc comments.

Test plan

  • `cargo check -p ldraw -p ldraw-ir` passes
  • `cargo doc -p ldraw -p ldraw-ir --no-deps` produces no intra-doc-link warnings

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) <[email protected]>
Copilot AI review requested due to automatic review settings May 13, 2026 16:23
Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR improves API documentation by clearly defining the semantics of the local: bool flag across library loading, resolution lookup, and part baking entry points, including the requirement that the bake-time and resolution-time local values must match to avoid incorrect sub-part resolution.

Changes:

  • Documented local: bool semantics on LibraryLoader::load_ref.
  • Documented lookup behavior and the meaning of the returned bool on ResolutionResult::query.
  • Documented local: bool semantics (and mismatch hazard) for bake_part_from_multipart_document and referenced it from bake_part_from_document.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File Description
ldraw/src/library.rs Adds rustdoc clarifying local resolution/search behavior for load_ref and ResolutionResult::query (including meaning of the returned bool).
ir/src/part.rs Adds rustdoc explaining how local affects sub-part resolution during baking and that it must match the value used during dependency resolution.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants