Skip to content

tutorials: stale-comment + panic-model fixes (audit followup)#3126

Merged
borisbat merged 1 commit into
masterfrom
bbatkin/tutorials-followup-comments
Jun 13, 2026
Merged

tutorials: stale-comment + panic-model fixes (audit followup)#3126
borisbat merged 1 commit into
masterfrom
bbatkin/tutorials-followup-comments

Conversation

@borisbat

Copy link
Copy Markdown
Collaborator

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

File Fix Verified against
tutorials/language/30_json.das Variant output comment was missing the $variant discriminator — actual output is {"$variant":0,"circle":5} ran the tutorial
tutorials/dasStbImage/03_transforms.das Default resize filter is Catmull-Rom only when upscaling, Mitchell when downscaling (the tutorial's resize(16,16) downsamples a 64×64, so it actually uses Mitchell) stb_image_resize2.h 846-852 + filter resolution at 6578
tutorials/integration/c/03_binding_types.c das_enumeration_make's third arg is the boolean ext (non-zero = int64 storage), not a 0=int8/1=int32/2=int16 selector include/daScript/daScriptC.h:382
doc/source/reference/tutorials/21_error_handling.rst Added a note: try/recover resumes mechanically, but a panic means a broken program — recover is for diagnostics-before-exit, not soft-error recovery; soft errors → Option/Result CLAUDE.md panic model; probe-confirmed control flow

Not changed (audit over-flag)

The audit also flagged 09_aot.c's daslang.exe -aot script.das script.das.cpp line as wrong. It isn't — that direct form is valid (utils/daScript/main.cpp:510-515 routes argv[1] == "-aot" to das_aot_main). The RST shows the alternate utils/aot/main.das -- -aot ... form; both work. Left as-is.

Verification

preflight --only format,lint,docs8 passed, 0 failed (both sphinx-html and sphinx-latex with -W; only pdflatex skipped — no local TeX). The two .das edits are comment-only; the .c edit is comment-only.

🤖 Generated with Claude Code

…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>
Copilot AI review requested due to automatic review settings June 13, 2026 06:48

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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.das variant JSON output comment to include the $variant discriminator.
  • Clarify dasStbImage resize 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.)
@borisbat borisbat merged commit 8ceed65 into master Jun 13, 2026
33 checks passed
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