Add some comments to external APIs

.changeset/strange-yaks-train.md

@@ -0,0 +1,6 @@
+---
+"@khanacademy/perseus-core": patch
+"@khanacademy/perseus-score": patch
+---
+
+Add comments to external-facing functions

packages/perseus-core/src/utils/split-perseus-item.ts

@@ -6,8 +6,9 @@ import {getUpgradedWidgetOptions} from "../widgets/upgrade";
 import type {PerseusRenderer} from "../data-schema";
 
 /**
- * Upgrades widget options and removes answerful data for all the widgets in a
- * Perseus item.
+ * Return a copy of a Perseus item with rubric data removed (ie answers)
+ *
+ * @param originalItem - the original, full Perseus item (which includes the rubric - aka answer data)
  */
 export default function splitPerseusItem(
     originalItem: PerseusRenderer,

packages/perseus-score/src/score.ts

@@ -122,7 +122,13 @@ export function flattenScores(widgetScoreMap: {
     return Object.values(widgetScoreMap).reduce(combineScores, noScore);
 }
 
-// once scorePerseusItem is the only one calling scoreWidgetsFunctional
+/**
+ * score a Perseus item
+ *
+ * @param perseusRenderData - the full answer data, includes the correct answer
+ * @param userInputMap - the user's input for each widget, mapped by ID
+ * @param locale - string locale for math parsing ("de" 1.000,00 vs "en" 1,000.00)
+ */
 export function scorePerseusItem(
     perseusRenderData: PerseusRenderer,
     userInputMap: UserInputMap,