Improve schema and user input type documentation

[jeremywiebe]

Summary:

This PR is strictly comment changes.

We have decent coverage of comments in data-schema.ts, but they are not JSDoc comments, and so many tools don't display these comments with the type where it's used. This PR converts all relevant // ... comments to true JSDoc comments /** ... */.

We also add/enhance JSDoc comments for all user input, validation, and rubric types in validation.types.ts.

This should help human authors as they work with these types, but we anticipate it also helping AI agents to understand the types much better.

NOTE: The Schema Change check triggered but as you can see in the diff, it's only comment changes so it's a false report. Eventually we should probably filter comments out from that diff.

EDIT: The schema change check has been fixed to ignore comments!

Issue: LEMS-3949

Test plan:

This is strictly documentation, so reading new comments would be helpful.

[github-actions]

🗄️ Schema Change: No Changes ✅

[github-actions]

Size Change: 0 B

Total Size: 486 kB

ℹ️ View Unchanged

Filename	Size
packages/kas/dist/es/index.js	20.5 kB
packages/keypad-context/dist/es/index.js	1 kB
packages/kmath/dist/es/index.js	5.96 kB
packages/math-input/dist/es/index.js	98.5 kB
packages/math-input/dist/es/strings.js	1.61 kB
packages/perseus-core/dist/es/index.item-splitting.js	11.8 kB
packages/perseus-core/dist/es/index.js	24.9 kB
packages/perseus-editor/dist/es/index.js	100 kB
packages/perseus-linter/dist/es/index.js	8.82 kB
packages/perseus-score/dist/es/index.js	9.4 kB
packages/perseus-utils/dist/es/index.js	403 B
packages/perseus/dist/es/index.js	188 kB
packages/perseus/dist/es/strings.js	7.47 kB
packages/pure-markdown/dist/es/index.js	1.39 kB
packages/simple-markdown/dist/es/index.js	6.71 kB

_{compressed-size-action}

[github-actions]

🛠️ Item Splitting: No Changes ✅

[github-actions]

npm Snapshot: Published

Good news!! We've packaged up the latest commit from this PR (def849b) and published it to npm. You
can install it using the tag PR3357.

Example:

pnpm add @khanacademy/perseus@PR3357

If you are working in Khan Academy's frontend, you can run the below command.

./dev/tools/bump_perseus_version.ts -t PR3357

If you are working in Khan Academy's webapp, you can run the below command.

./dev/tools/bump_perseus_version.js -t PR3357

[jeremywiebe]

@nishasy @ivyolamit this is correct right? Inline image use is deprecated (thinking to dissuade AI agents that might see this field and want to use inline images)

[nishasy]

Yes, that's correct! We don't want markdown images in content anymore, just image widgets.

Note: We still need markdown images in nested widget content, like radio.

[jeremywiebe]

@claude review

[anakaren-rojas]

This looks great! Should we add this as a repo rule or a short doc so we’re consistent on when to use JSDoc vs regular comments?

[benchristel]

Thanks for improving these doc comments! I left a few suggestions inline, but LGTM overall!

[benchristel]

These comments ("Provided on Khan Academy when true.") imply that the ItemExtras is a record with defined keys, but it's actually a tuple of constants that is used to generate that record type.

No action needed on this PR, since you're just improving formatting.

[benchristel]

Is there any reason to set a string for maxError, or is that deprecated?

[jeremywiebe]

This is historical data fun. There are items in our published content where this value is a string-encoded number, not an actual JSON number.

I wonder if this is something we could resolve in the parser so we can type this as simply number?

Right now the parser is:

maxError: optional(union(number).or(string).parser),

But perhaps we could simply parse the string to a floating point number and fix this?

[benchristel]

We can try that! I suspect the reason I didn't do it the first time around is that there are some non-numeric maxError string values in our data. But if we can figure out how the existing code handles that case, then we can fix the data in the parser to be consistent with that.

[jeremywiebe]

I'll look at that in a separate PR, but a quick search of (at least en) published content shows we don't have any string values that aren't parsable numbers:

rg '"type"\s*:\s*"input-number"' -l | xargs jq '.. | objects | select(has("type") and .type == "input-number" and ((.options.maxError | type) == "string")) | {file: input_filename, maxError: .options.maxError, isValid: .options.maxError | try (tonumber | true) catch false } | select(.isValid == false)'
# No rows printed!

[Myranae]

@claude review

[claude]

🟡 Nit: The JSDoc for PerseusNumericInputWidgetOptions.answers in data-schema.ts still says "A list of all the possible correct and incorrect answers" but the corresponding PerseusNumericInputRubric.answers in validation.types.ts was updated per benchristel's review feedback to drop "all the possible" (since the list is not exhaustive). Consider aligning this description to match.

Extended reasoning...

What the bug is

The JSDoc for PerseusNumericInputWidgetOptions.answers at data-schema.ts:1447 reads:

/** A list of all the possible correct and incorrect answers */

Meanwhile, the corresponding field PerseusNumericInputRubric.answers in validation.types.ts:486 was updated (per reviewer benchristel's feedback in PR comment #12: "All possible correct and incorrect answers is a strong claim") to:

/**
 * A list of correct and incorrect answers. Each answer can have a
 * message explaining why it is correct/incorrect. There may be
 * multiple correct answers if multiple formats are accepted. For
 * example, some questions might accept either a fraction or a
 * decimal as correct.
 *
 * The first answer that matches (correct or incorrect) is the scoring
 * result (so order of answers is very important).
 */

How this inconsistency was introduced

The PR converted existing // comments to /** */ JSDoc comments in data-schema.ts. The old // comment already said "all the possible", and it was promoted to JSDoc verbatim. When benchristel flagged the same phrasing in validation.types.ts, the author updated only that file, leaving data-schema.ts with the stale wording.

Why the phrase is inaccurate

As benchristel noted, the answers array does not contain an exhaustive enumeration of every possible correct and incorrect answer. It typically contains common answers with explanatory messages — for instance, a few specific wrong answers that learners commonly give, along with explanations of why they're wrong. The phrase "all the possible" overstates what the field contains.

Impact

This is a minor documentation inconsistency. Since the PR's explicit goal is improving documentation for both human developers and AI agents, having divergent descriptions of the same concept across the two canonical type files undermines that goal. An AI agent reading the data-schema.ts JSDoc would form a different (and less accurate) understanding of the field than one reading validation.types.ts.

Suggested fix

Update data-schema.ts:1447 to align with the corrected validation.types.ts wording, e.g.:

/**
 * A list of correct and incorrect answers. Each answer can have a
 * message explaining why it is correct/incorrect.
 */
answers: PerseusNumericInputAnswer[];

[claude]

🟡 The sinusoid and tangent JSDoc formulas say y = a*sin(bx + c) + d and y = a*tan(bx + c) + d, but the implementation uses subtraction: a * Math.sin(b * x - c) + d and a * Math.tan(b * x - c) + d. Both formulas should use bx - c to match the code.

Extended reasoning...

What the bug is

The new JSDoc comments for the sinusoid variant (line 751) and tangent variant (line 762) of GrapherAnswerTypes in data-schema.ts describe the function forms as y = asin(bx + c) + d and y = atan(bx + c) + d respectively. However, the actual implementation uses subtraction (- c), not addition (+ c).

The specific code paths

The implementation in grapher-util.ts consistently uses - c:

• canonicalSineCoefficients (line 24) documents the form as f(x) = a * Sin(b * x - c) + d
• getFunctionForCoeffs for sinusoid (line 238) computes a * Math.sin(b * x - c) + d
• getEquationString for sinusoid (line 260) displays sin(bx - c)
• canonicalTangentCoefficients (line 59) documents the form as f(x) = a * Tan(b * x - c) + d
• getFunctionForCoeffs for tangent (line 304) computes a * Math.tan(b * x - c) + d
• getEquationString for tangent (line 318) displays tan(bx - c)

Why existing code does not prevent it

This is purely a documentation error introduced by this PR. The runtime behavior is correct - the implementation consistently uses - c. The JSDoc simply has the wrong sign.

Step-by-step proof

Consider a sinusoid with coefficients [a=1, b=1, c=pi/2, d=0]. The implementation computes Math.sin(x - pi/2), which equals -cos(x) (a rightward phase shift of pi/2). The JSDoc formula sin(x + pi/2) would instead equal cos(x) (a leftward phase shift of pi/2) - a completely different function. The sign of c determines the phase shift direction: - c shifts right, + c shifts left.

Impact

Since this PR is specifically a documentation improvement aimed at helping developers and AI agents understand the types, the wrong sign in the formula could lead to incorrect reasoning about phase shifts. An AI agent reading this JSDoc would compute the wrong function when trying to match parameters to graph coordinates.

Fix

Change both formulas from bx + c to bx - c:

• Sinusoid: y = a*sin(bx - c) + d
• Tangent: y = a*tan(bx - c) + d