Document runner file-IO and glob helpers; add theme example (#346)#382
Open
leynos wants to merge 2 commits into
Open
Document runner file-IO and glob helpers; add theme example (#346)#382leynos wants to merge 2 commits into
leynos wants to merge 2 commits into
Conversation
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
WalkthroughRustdoc comments are added to four files with no runtime or signature changes. The glob normalisation helpers ( ChangesRustdoc Additions
Suggested labels
Caution Pre-merge checks failedPlease resolve all errors before merging. Addressing warnings is optional.
❌ Failed checks (1 error)
✅ Passed checks (19 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![codescene-delta-analysis[bot]](https://avatars.githubusercontent.com/in/53921?s=60&v=4){kind=small}
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
9 tasks
First increment of the Rustdoc-coverage work, delivering the concrete "missing Rustdoc on public/crate-visible helpers" acceptance item. Document the previously undocumented runner process file-I/O helpers in `src/runner/process/file_io.rs` (`create_temp_ninja_file`, `write_text_file_utf8`, `write_ninja_file`, `write_text_file`, `write_ninja_stdout`, `write_text_stdout`), each with a summary and an `# Errors` section. These are `pub` but only crate-reachable (the `process` module is private), so `missing_docs` never flagged them. Document the glob helper functions `normalize_separators`, `force_literal_escapes`, and `validate_brace_matching`, including the brace-validation `# Errors` contract. Add a worked `# Examples` doctest to the high-use public `ThemePreference::parse_raw`, exercising the trim/case-insensitive and error paths. Remaining `# Examples` coverage for the other high-use public APIs is staged as follow-up increments per the issue's "highest-use first" guidance.
lodyai
Bot
force-pushed
the
issue-346-rustdoc-examples
branch
from
41c456c to
0a7011e
Compare
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@src/manifest/glob/normalize.rs`:
- Around line 3-8: The documentation comments for the `normalize_separators` and
`force_literal_escapes` functions in src/manifest/glob/normalize.rs are too
broad and conflate the responsibilities of separate steps in the glob pipeline.
Update the doc comment for `normalize_separators` (lines 3-8) to clarify that it
only rewrites forward slashes to the platform separator and preserves backslash
escapes for a follow-up literal-escape pass rather than treating them as
separators. Also update the doc comment for `force_literal_escapes` (lines
84-88) to specify that it only rewrites a small fixed set of selected escaped
metacharacters (not all escapes) into bracket character classes, and remove
language suggesting it expands all escapes.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 9334ccb0-2ce8-4246-97b6-30ba4fd3ce62
📒 Files selected for processing (4)
src/manifest/glob/normalize.rssrc/manifest/glob/validate.rssrc/runner/process/file_io.rssrc/theme.rs
Comment on lines
+3
to
+8
| /// Normalise path separators in a glob `pattern` to the platform-native one. | ||
| /// | ||
| /// Forward slashes (and, on Unix, backslash sequences) are rewritten to | ||
| /// [`std::path::MAIN_SEPARATOR`] so manifests can use `/` portably. On Unix the | ||
| /// backslash also acts as an escape, so escaped metacharacters are preserved | ||
| /// rather than treated as separators. |
Contributor
There was a problem hiding this comment.
Tighten the escape docs.
normalize_separators and force_literal_escapes are separate steps in the glob pipeline, but the current wording makes both sound broader than they are. normalize_separators does not own the later literal-escape rewrite, and force_literal_escapes only expands a small fixed set of metacharacters outside character classes.
Suggested wording
@@
-/// Forward slashes (and, on Unix, backslash sequences) are rewritten to
-/// [`std::path::MAIN_SEPARATOR`] so manifests can use `/` portably. On Unix the
-/// backslash also acts as an escape, so escaped metacharacters are preserved
-/// rather than treated as separators.
+/// Forward slashes are rewritten to [`std::path::MAIN_SEPARATOR`] so manifests
+/// can use `/` portably. On Unix, backslash escapes are preserved for the
+/// follow-up literal-escape pass rather than being treated as separators here.
@@
-/// Rewrite backslash escapes into bracket character classes (Unix only).
+/// Rewrite the Unix-only escaped metacharacters handled by this helper into
+/// bracket character classes.
@@
-/// The `glob` crate treats `\` literally on Unix, so an escaped metacharacter
-/// such as `\*` is converted to the single-element class `[*]` to match the
-/// literal character. Returns the pattern with all escapes expanded.
+/// The `glob` crate treats `\` literally on Unix, so selected escaped
+/// metacharacters such as `\*` are converted to the single-element class `[*]`
+/// to match the literal character.Matches the GlobPattern::new pipeline and the glob tests.
Also applies to: 84-88
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/manifest/glob/normalize.rs` around lines 3 - 8, The documentation
comments for the `normalize_separators` and `force_literal_escapes` functions in
src/manifest/glob/normalize.rs are too broad and conflate the responsibilities
of separate steps in the glob pipeline. Update the doc comment for
`normalize_separators` (lines 3-8) to clarify that it only rewrites forward
slashes to the platform separator and preserves backslash escapes for a
follow-up literal-escape pass rather than treating them as separators. Also
update the doc comment for `force_literal_escapes` (lines 84-88) to specify that
it only rewrites a small fixed set of selected escaped metacharacters (not all
escapes) into bracket character classes, and remove language suggesting it
expands all escapes.
Tighten the Rustdoc for the glob separator and literal-escape helpers so each comment describes only its own pipeline step.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes #346
First increment of the staged Rustdoc-coverage work. It fully delivers the issue's concrete "missing Rustdoc on public runner/glob helpers is filled in" acceptance item, plus a representative
# Examplessection on a highest-use public API.Changes
src/runner/process/file_io.rs: document the six previously undocumented file-I/O helpers (create_temp_ninja_file,write_text_file_utf8,write_ninja_file,write_text_file,write_ninja_stdout,write_text_stdout) with summaries and# Errorssections. These arepubbut only crate-reachable (theprocessmodule is private), somissing_docsnever flagged them — exactly the "crate-visible helpers" the issue calls out.src/manifest/glob/{normalize,validate}.rs: documentnormalize_separators,force_literal_escapes, andvalidate_brace_matching(including the brace-validation# Errorscontract).src/theme.rs: add a worked# Examplesdoctest toThemePreference::parse_rawcovering the trim/case-insensitive and error paths.Scope note
Per the issue's "add examples to the highest-use public APIs first, then work through remaining," the broader
# Examplescoverage forsrc/status.rs,src/stdlib/config.rs,src/cli/parser.rs,src/runner/mod.rs,src/ast.rs, and thetest_supportenv guards is staged as follow-up increments; this PR lands the missing-helper-docs item and a representative example.Validation
make check-fmt/make lint(cargo doc, warnings denied) /make test(doctests) — pass (37 suites)🤖 Generated with Claude Code