From 44b6f338772acb1d71ab992226ed11ead1135419 Mon Sep 17 00:00:00 2001
From: Jim O'Donnell <jim@zooniverse.org>
Date: Sun, 18 Feb 2024 15:33:34 +0000
Subject: [PATCH] Clarify the annotation value

---
 .../tasks/drawing/models/DrawingAnnotation.js    | 14 ++++++++++----
 .../models/TranscriptionAnnotation.js            | 16 ++++++++++------
 2 files changed, 20 insertions(+), 10 deletions(-)

diff --git a/packages/lib-classifier/src/plugins/tasks/drawing/models/DrawingAnnotation.js b/packages/lib-classifier/src/plugins/tasks/drawing/models/DrawingAnnotation.js
index 3a3bcdc4ada..2741762a6be 100644
--- a/packages/lib-classifier/src/plugins/tasks/drawing/models/DrawingAnnotation.js
+++ b/packages/lib-classifier/src/plugins/tasks/drawing/models/DrawingAnnotation.js
@@ -19,6 +19,11 @@ const Drawing = types.model('Drawing', {
       return resolveIdentifier(DrawingTask, getRoot(self), self.task)
     },
 
+    /**
+    Generate a snapshot in the format expected by Panoptes, Caesar etc.
+    See ADR 25.
+    https://github.com/zooniverse/front-end-monorepo/blob/master/docs/arch/adr-25.md
+    */
     toSnapshot() {
       const snapshot = getSnapshot(self)
       // Replace mark references (IDs) with mark snapshots.
@@ -29,9 +34,9 @@ const Drawing = types.model('Drawing', {
       const drawingAnnotations = [drawingSnapshot]
       markSnapshots.forEach((markSnapshot, markIndex) => {
         const mark = { ...markSnapshot }
-        // Map subtask keys to mark.details.
+        // `mark.details` is an array of subtask keys.
         mark.details = mark.annotations.map(annotation => ({ task: annotation.task }))
-        // Push mark.annotations to the returned array.
+        // Push mark subtask annotations to the returned array.
         mark.annotations.forEach(markAnnotation => {
           // Strip annotation IDs and add markIndex.
           const { id, ...rest } = markAnnotation
@@ -48,8 +53,9 @@ const Drawing = types.model('Drawing', {
   .actions(self => ({
     afterAttach() {
       function _onMarksChange() {
-        const newAnnotation = self.actualTask.marks.map(mark => mark.id)
-        self.update(newAnnotation)
+        // A drawing annotation stores an array of mark IDs for the corresponding task.
+        const newValue = self.actualTask.marks.map(mark => mark.id)
+        self.update(newValue)
       }
 
       addDisposer(self, autorun(_onMarksChange))
diff --git a/packages/lib-classifier/src/plugins/tasks/experimental/transcription/models/TranscriptionAnnotation.js b/packages/lib-classifier/src/plugins/tasks/experimental/transcription/models/TranscriptionAnnotation.js
index ef98af4473e..ff7642cff36 100644
--- a/packages/lib-classifier/src/plugins/tasks/experimental/transcription/models/TranscriptionAnnotation.js
+++ b/packages/lib-classifier/src/plugins/tasks/experimental/transcription/models/TranscriptionAnnotation.js
@@ -16,8 +16,11 @@ const Transcription = types.model('Transcription', {
       return resolveIdentifier(TranscriptionTask, getRoot(self), self.task)
     },
 
-    // This is a copy of DrawingAnnotation's toSnapshot with the exception of
-    // Changing the task type to TranscriptionTask
+    /**
+    Generate a snapshot in the format expected by Panoptes, Caesar etc.
+    See ADR 25.
+    https://github.com/zooniverse/front-end-monorepo/blob/master/docs/arch/adr-25.md
+    */
     toSnapshot() {
       const snapshot = getSnapshot(self)
       // Replace mark references (IDs) with mark snapshots.
@@ -28,9 +31,9 @@ const Transcription = types.model('Transcription', {
       const drawingAnnotations = [drawingSnapshot]
       markSnapshots.forEach((markSnapshot, markIndex) => {
         const mark = { ...markSnapshot }
-        // Map subtask keys to mark.details.
+        // `mark.details` is an array of subtask keys.
         mark.details = mark.annotations.map(annotation => ({ task: annotation.task }))
-        // Push mark.annotations to the returned array.
+        // Push mark subtask annotations to the returned array.
         mark.annotations.forEach(markAnnotation => {
           // Strip annotation IDs and add markIndex.
           const { id, ...rest } = markAnnotation
@@ -47,8 +50,9 @@ const Transcription = types.model('Transcription', {
   .actions(self => ({
     afterAttach() {
       function _onMarksChange() {
-        const newAnnotation = self.actualTask.marks.map(mark => mark.id)
-        self.update(newAnnotation)
+        // A drawing annotation stores an array of mark IDs for the corresponding task.
+        const newValue = self.actualTask.marks.map(mark => mark.id)
+        self.update(newValue)
       }
 
       addDisposer(self, autorun(_onMarksChange))