Clarify the annotation value

zooniverse · Mar 15, 2024 · cf4acb3 · cf4acb3
1 parent ce98b4f
commit cf4acb3
Show file tree

Hide file tree

Showing 2 changed files with 20 additions and 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
@@ -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/...classifier/src/plugins/tasks/experimental/transcription/models/TranscriptionAnnotation.js b/...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))