Refer to server docs for Puzzle fields

pkg/transpile/puzzle.go

@@ -37,23 +37,45 @@ type PuzzleDebug struct {
 	Summary string
 }
 
-// Puzzle contains everything about a puzzle that a client would see.
+// Puzzle contains everything about a puzzle that a client will see.
 type Puzzle struct {
-	Debug         PuzzleDebug
-	Authors       []string
-	Attachments   []string
-	Scripts       []string
-	Body          string
+	// Debug contains debugging information, omitted in mothballs
+	Debug PuzzleDebug
+
+	// Authors names all authors of this puzzle
+	Authors []string
+
+	// Attachments is a list of filenames used by this puzzle
+	Attachments []string
+
+	// Scripts is a list of EMCAScript files needed by the client for this puzzle
+	Scripts []string
+
+	// Body is the HTML rendering of this puzzle
+	Body string
+
+	// AnswerPattern contains the pattern (regular expression?) used to match valid answers
 	AnswerPattern string
-	AnswerHashes  []string
-	Objective     string
-	KSAs          []string
-	Success       struct {
+
+	// AnswerHashes contains hashes of all answers for this puzzle
+	AnswerHashes []string
+
+	// Objective is the learning objective for this puzzle
+	Objective string
+
+	// KSAs lists all KSAs achieved upon successfull completion of this puzzle
+	KSAs []string
+
+	// Success lists the criteria for successfully understanding this puzzle
+	Success struct {
+		// Acceptable describes the minimum work required to be considered successfully understanding this puzzle's concepts
 		Acceptable string
-		Mastery    string
+
+		// Mastery describes the work required to be considered mastering this puzzle's conceptss
+		Mastery string
 	}
 
-	// Answers will be empty in a mothball
+	// Answers lists all acceptable answers, omitted in mothballs
 	Answers []string
 }
 

theme/moth.mjs

@@ -26,11 +26,14 @@ class Award {
  * A puzzle.
  * 
  * A new Puzzle only knows its category and point value.
- * If you want to populate it with meta-information, you must call Get().
+ * If you want to populate it with meta-information, you must call Populate().
+ * 
+ * Parameters created by Populate are described in the server source code:
+ * {@link https://pkg.go.dev/github.com/dirtbags/moth/v4/pkg/transpile#Puzzle}
+ * 
  */
 class Puzzle {
     /**
-     * 
      * @param {Server} server 
      * @param {String} category 
      * @param {Number} points 
@@ -44,71 +47,22 @@ class Puzzle {
          * @type {Server}
          */
         this.server = server
-        /** Category this puzzle belongs to
-         * @type {String}
-         */
-        this.Category = category
-        /** Point value of this puzzle
-         * @type {Number}
-         */
-        this.Points = points
-    }
+        
+        /** Category this puzzle belongs to */
+        this.Category = String(category)
+        
+        /** Point value of this puzzle */
+        this.Points = Number(points)
 
-    /** Error returned trying to fetch this puzzle */
-    Error = {
-        /** Status code provided by server */
-        Status: 0,
-        /** Status text provided by server */
-        StatusText: "",
-        /** Full text of server error */
-        Body: "",
-    }
-    /** Hashes of answers 
-     * @type {String[]}
-     */
-    AnswerHashes = []
-    /** Pattern that answer should match
-     * @type {String[]}
-     */
-   AnswerPattern = ""
-    /** Accepted answers 
-     * @type {String[]}
-     */
-    Answers = []
-    /** Other files attached to this puzzles 
-     * @type {String[]}
-     */
-    Attachments = []
-    /** This puzzle's authors 
-     * @type {String[]}
-    */
-    Authors = []
-    /** HTML body of this puzzle */
-    Body = ""
-    /** Debugging information */
-    Debug = {
-        Errors: [],
-        Hints: [],
-        Log: [],
-        Notes: "",
-        Summary: "",
-    }
-    /** KSAs met by solving this puzzle 
-     * @type {String[]}
-    */
-    KSAs = []
-    /** Learning objective for this puzzle */
-    Objective = "" 
-    /** ECMAScript scripts needed for this puzzle 
-     * @type {String[]}
-    */
-    Scripts = []
-    /** Criteria for succeeding at this puzzle */
-    Success = {
-        /** Acceptable Minimum criteria for success */
-        Minimum: "",
-        /** Criteria for demonstrating mastery of this puzzle */
-        Mastery: "",
+        /** Error returned trying to fetch this puzzle */
+        this.Error = {
+            /** Status code provided by server */
+            Status: 0,
+            /** Status text provided by server */
+            StatusText: "",
+            /** Full text of server error */
+            Body: "",
+        }
     }
 
     /**

theme/reports/ksa.mjs

@@ -20,19 +20,15 @@ async function init() {
     let state = await server.GetState()
 
     doing("Retrieving all puzzles")
-    let puzzles = state.Puzzles()
-    for (let p of puzzles) {
-        await p.Populate().catch(x => {})
-    }
-
-    doing("Filling table")
     let puzzlerowTemplate = document.querySelector("template#puzzlerow")
-    for (let tbody of document.querySelectorAll("tbody")) {
-        for (let puzzle of puzzles) {
+    let puzzles = state.Puzzles()
+    for (let puzzle of puzzles) {
+        await puzzle.Populate().catch(x => {})
+        for (let tbody of document.querySelectorAll("tbody")) {
             let row = puzzlerowTemplate.content.cloneNode(true)
             row.querySelector(".category").textContent = puzzle.Category
             row.querySelector(".points").textContent = puzzle.Points
-            row.querySelector(".ksas").textContent = puzzle.KSAs.join(" ")
+            row.querySelector(".ksas").textContent = (puzzle.KSAs || []).join(" ")
             row.querySelector(".error").textContent = puzzle.Error.Body
             tbody.appendChild(row)
         }