docs: add docstrings and comments to complex functions

[LalatenduMohanty]

Add docstrings to functions and inline comments to non-obvious code patterns across various files. Only targets genuinely complex logic that would be hard for new contributors to understand.

Though my goal was to help contributors but it has also a positive impact on AI code assistants. When an AI assistant needs to understand a function, it either reads the docstring or reads the entire function body. A good docstring lets it understand the function's purpose and behavior without consuming context window on implementation details.

Closes: #1046

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds docstrings and inline comments to multiple complex functions across src/fromager (finders, resolver, bootstrapper, wheels, sources, dependencies, pyproject, external_commands, requirements_file, dependency_graph, vendor_rust), documenting lookup strategies, filtering pipelines, and behavior of plugin/clone flows. It also introduces three functional changes: bootstrapper now re-extracts a wheel’s build tag and rejects mismatches; dependencies passes the parent requirement’s extras into marker evaluation; and requirements_file evaluates markers using a separate marker environment per extra value.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

🚥 Pre-merge checks | ✅ 3 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Out of Scope Changes check	❓ Inconclusive	All changes are in-scope documentation additions. The PR includes a minor functional change in bootstrapper.py (_look_for_existing_wheel re-extracts build_tag) and a behavioral clarification in requirements_file.py (evaluate_marker per-extra environment), which are documented in the summaries but appear to be pre-existing behaviors being documented rather than new functionality.	Verify whether the build_tag re-extraction in bootstrapper.py and the marker evaluation changes in requirements_file.py are functional improvements tied to issue #1046 or separate bug fixes that should be tracked separately.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: adding docstrings and comments to complex functions throughout the codebase.
Linked Issues check	✅ Passed	The PR fully addresses issue #1046 by adding docstrings to all 12 specified functions (find_sdist, find_wheel, find_source_dir, get_project_from_pypi, _resolve_version_from_git_url, add_extra_metadata_to_wheels, extract_info_from_wheel_file, download_url, prepare_source, get_build_backend_hook_caller, _update_build_requires, run) plus additional comments as requested.
Description check	✅ Passed	The PR description accurately relates to the changeset: adding docstrings and inline comments to complex functions across multiple files to improve contributor onboarding.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/fromager/bootstrapper.py (1)

1081-1089: ⚠️ Potential issue | 🟠 Major

Handle invalid cached wheel filenames as cache misses.

At Line 1084, a parse failure from extract_info_from_wheel_file() can abort bootstrap during cache lookup. This path should degrade to “not cached” and continue.

Proposed fix

-        _, _, build_tag, _ = wheels.extract_info_from_wheel_file(req, wheel_filename)
+        try:
+            _, _, build_tag, _ = wheels.extract_info_from_wheel_file(
+                req, wheel_filename
+            )
+        except ValueError as err:
+            logger.info(
+                "ignoring cached artifact with invalid wheel filename %s: %s",
+                wheel_filename,
+                err,
+            )
+            return None, None

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/fromager/bootstrapper.py` around lines 1081 - 1089, The call to
wheels.extract_info_from_wheel_file(req, wheel_filename) may raise a parse error
and currently can abort bootstrap; wrap that call in a try/except that catches
the parse/validation exception (e.g., ValueError or the specific exception
raised by extract_info_from_wheel_file) and treat it as a cache miss by logging
a debug/info message and returning (None, None) so execution continues; update
the logic around extract_info_from_wheel_file and the subsequent
expected_build_tag check to rely on the safe, exception-handled result.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Outside diff comments:
In `@src/fromager/bootstrapper.py`:
- Around line 1081-1089: The call to wheels.extract_info_from_wheel_file(req,
wheel_filename) may raise a parse error and currently can abort bootstrap; wrap
that call in a try/except that catches the parse/validation exception (e.g.,
ValueError or the specific exception raised by extract_info_from_wheel_file) and
treat it as a cache miss by logging a debug/info message and returning (None,
None) so execution continues; update the logic around
extract_info_from_wheel_file and the subsequent expected_build_tag check to rely
on the safe, exception-handled result.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: cc6ee430-a315-4dbc-8dac-78e8d6cb8470

📥 Commits

Reviewing files that changed from the base of the PR and between b8f4441 and 14113ea.

📒 Files selected for processing (11)

• src/fromager/bootstrapper.py
• src/fromager/dependencies.py
• src/fromager/dependency_graph.py
• src/fromager/external_commands.py
• src/fromager/finders.py
• src/fromager/pyproject.py
• src/fromager/requirements_file.py
• src/fromager/resolver.py
• src/fromager/sources.py
• src/fromager/vendor_rust.py
• src/fromager/wheels.py