Skip to content

Stop truncating theory pages at the first exercise without a description - #322

Merged
nank1ro merged 1 commit into
mainfrom
fix/theory-skip-missing-description
Sep 17, 2026
Merged

nank1ro merged 1 commit into
mainfrom
fix/theory-skip-missing-description

Conversation

@nank1ro

@nank1ro nank1ro commented Sep 17, 2026

Copy link
Copy Markdown
Owner

theory_creator builds each argument's _theory.md by concatenating the # --description-- of every exercise in order. On the first exercise without one it ran break, abandoning the rest of the folder.

Most arguments only describe their first few exercises, so break and continue usually agree. But 27 arguments have a described exercise after an undescribed one, and that text never reached learners in any of the 12 locales:

file theory that was dropped
en/javascript/strings/11.md trim() / trimStart() / trimEnd()
en/swift/lambda/12.md returning a closure from a function
en/dart/maps/9.md typed empty map literals <K, V>{}

Change

One line — break → continue — plus regenerated theory. The regeneration is purely additive: 326 _theory.md files, 17051 insertions, 0 deletions. No existing theory text changes content or order.

Errors found in the newly surfaced text

Independent review of the recovered paragraphs caught three factual errors, fixed here (en + all 11 locales):

  • dart/comments/6.md claimed "the analyser ignores all text unless it is enclosed in square brackets". Brackets are reference syntax; ordinary prose is kept as documentation.
  • python/errorHandling/15.md claimed raising a new exception "throws away the original traceback" — contradicting the same argument's later raise ... from e explanation. Python keeps the original as __context__.
  • es/python/conditionalStatements/{7,16,35}.md claimed Python requires the if condition in parentheses. (es/javascript/conditionalStatements uses the same wording and was left alone — JS does require them.)

Checks

  • validator: +275436: All tests passed!
  • dart analyze on theory_creator: no issues
  • git diff --numstat over *_theory.md: 0 deletions across all 326 files

Known, not fixed here

  • scripts/check_locales.py reports 11 false DIFF … [answers] on dart/comments/6.md. Its strip_comments() deliberately refuses to enter block-comment state when no closing */ exists, so the /* and /** multiple-choice tokens in that exercise keep their (legitimately translated) text. Not run in CI; pre-existing.
  • Spanish has 77 --description-- blocks with no en counterpart, machine-generated filler confined to es/{python,javascript}/conditionalStatements. 43 become visible with this change. Only the factually wrong ones are corrected here; whether to keep or drop the rest is a content call.

theory_creator concatenated each argument's exercise descriptions into
_theory.md but hit break on the first exercise without one, abandoning the
rest of the folder. 27 arguments have described exercises after an
undescribed one, so their theory never reached learners in any locale -
e.g. trim()/trimStart()/trimEnd() in javascript/strings, returning a
closure in swift/lambda, typed empty map literals in dart/maps.

break -> continue. Regenerating is purely additive: 326 _theory.md files,
17051 insertions, 0 deletions.

Review of the newly surfaced text found three factual errors, fixed here:
- dart/comments/6.md claimed the analyser ignores doc-comment prose unless
  bracketed; brackets are reference syntax, not a filter.
- python/errorHandling/15.md claimed raising a new exception throws away
  the original traceback, contradicting the same argument's 'raise ... from e'
  explanation.
- es/python/conditionalStatements/{7,16,35}.md claimed Python requires the
  if condition in parentheses.
@nank1ro
nank1ro merged commit f767eb7 into main Sep 17, 2026
4 checks passed
@nank1ro
nank1ro deleted the fix/theory-skip-missing-description branch September 17, 2026 06:22
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.

1 participant