tutorials: stale-comment + panic-model fixes (audit followup)#3126
Merged
Conversation
…llowup) Tier-C followup to the tutorial gap audit (#3125). Verified each claim against source before editing: - language/30_json.das: variant output comment was missing the $variant discriminator key; actual output is {"$variant":0,"circle":5} (confirmed by running the tutorial). - dasStbImage/03_transforms.das: default resize filter is Catmull-Rom only when upscaling, Mitchell when downscaling (stb_image_resize2.h lines 846-852 + resolution at 6578) -- the tutorial's resize(16,16) downsamples. - integration/c/03_binding_types.c: das_enumeration_make's third arg is the boolean 'ext' (non-zero = int64 storage), not a 0/1/2 int-type selector (daScriptC.h:382). - 21_error_handling.rst: add a note that try/recover resumes mechanically but panic means a broken program -- recover is for diagnostics before exit, not soft-error recovery; point soft errors at Option/Result. Note: the audit also flagged 09_aot.c's 'daslang.exe -aot ...' line, but that direct form is valid (utils/daScript/main.cpp:510-515 routes to das_aot_main), so it was left unchanged. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Follow-up tutorial/documentation correctness fixes from the tutorial gap audit, focusing on aligning tutorial comments/notes with actual runtime/library behavior.
Changes:
- Update
30_json.dasvariant JSON output comment to include the$variantdiscriminator. - Clarify
dasStbImageresize default filter behavior (upsample vs downsample). - Correct the
das_enumeration_make“ext” argument description in the C integration tutorial. - Add a note to the error handling RST about panic semantics and appropriate use of
recover.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| tutorials/language/30_json.das | Fixes the documented JSON output for variants to match the serializer’s $variant encoding. |
| tutorials/integration/c/03_binding_types.c | Corrects the explanation of das_enumeration_make(..., ext) to match the C API contract. |
| tutorials/dasStbImage/03_transforms.das | Clarifies the default resize filter selection depending on scaling direction. |
| doc/source/reference/tutorials/21_error_handling.rst | Adds a panic-model note about try/recover usage; suggests a small wording clarification. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+47
to
+48
| status value instead — see :ref:`tutorial_option_and_result`. (Consistent | ||
| with this, a ``finally`` block is skipped when its body panics.) |
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
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.
Tier-C quick-win followup to the tutorial gap audit (#3125): four small, low-risk fixes that the audit flagged but were out of scope for the main PR (source-file comments and one doc note). Each claim was verified against source before editing.
Changes
tutorials/language/30_json.das$variantdiscriminator — actual output is{"$variant":0,"circle":5}tutorials/dasStbImage/03_transforms.dasresize(16,16)downsamples a 64×64, so it actually uses Mitchell)stb_image_resize2.h846-852 + filter resolution at 6578tutorials/integration/c/03_binding_types.cdas_enumeration_make's third arg is the booleanext(non-zero =int64storage), not a0=int8/1=int32/2=int16selectorinclude/daScript/daScriptC.h:382doc/source/reference/tutorials/21_error_handling.rsttry/recoverresumes mechanically, but a panic means a broken program —recoveris for diagnostics-before-exit, not soft-error recovery; soft errors →Option/ResultNot changed (audit over-flag)
The audit also flagged
09_aot.c'sdaslang.exe -aot script.das script.das.cppline as wrong. It isn't — that direct form is valid (utils/daScript/main.cpp:510-515routesargv[1] == "-aot"todas_aot_main). The RST shows the alternateutils/aot/main.das -- -aot ...form; both work. Left as-is.Verification
preflight --only format,lint,docs— 8 passed, 0 failed (bothsphinx-htmlandsphinx-latexwith-W; onlypdflatexskipped — no local TeX). The two.dasedits are comment-only; the.cedit is comment-only.🤖 Generated with Claude Code