refactor: update doc format to use per-field .name/.datum structure

HanSur94 · claude · HanSur94 · commit 13ae6f070a40 · 2026-03-19T23:04:43.000+01:00
The external system's .doc field contains one sub-field per sensor,
each with .name (display name) and .datum (datenum field name).

- Extract shared extractDatenumField helper to private/
- Update loadModuleData and loadModuleMetadata to use new format
- Update all tests to match new .doc structure

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/libs/SensorThreshold/loadModuleData.m b/libs/SensorThreshold/loadModuleData.m
@@ -2,10 +2,11 @@
 %LOADMODULEDATA Match module struct fields to registered sensors and assign X/Y.
 %   sensors = loadModuleData(registry, moduleStruct) takes an
 %   ExternalSensorRegistry and a module struct loaded from the external
-%   system. The struct must contain a .doc.date field naming the datenum
-%   field. Each struct field whose name matches a registered sensor key
-%   gets its data assigned as sensor.Y, with the shared datenum as
-%   sensor.X.
+%   system. The struct must contain a .doc field where each sub-field has
+%   .name and .datum properties. The .datum value names the shared
+%   datenum field. Each struct field whose name matches a registered
+%   sensor key gets its data assigned as sensor.Y, with the shared
+%   datenum as sensor.X.
 %
 %   Returns a 1xN cell array of filled Sensor handles (empty 1x0 if no
 %   matches). Output order follows fieldnames(moduleStruct).
@@ -17,27 +18,8 @@
 
     narginchk(2, 2);
 
-    % --- Validate doc metadata ---
-    if ~isfield(moduleStruct, 'doc')
-        error('loadModuleData:missingDoc', ...
-            'Module struct must contain a ''doc'' field.');
-    end
-    if ~isfield(moduleStruct.doc, 'date')
-        error('loadModuleData:missingDocDate', ...
-            'Module struct .doc must contain a ''date'' field naming the datenum variable.');
-    end
-
-    datenumField = moduleStruct.doc.date;
-
-    if ~ischar(datenumField)
-        error('loadModuleData:invalidDocDate', ...
-            'Module struct .doc.date must be a char (field name), got %s.', class(datenumField));
-    end
-
-    if ~isfield(moduleStruct, datenumField)
-        error('loadModuleData:missingDatenum', ...
-            'Datenum field ''%s'' (from doc.date) not found in module struct.', datenumField);
-    end
+    % --- Extract datenum field name from doc metadata ---
+    datenumField = extractDatenumField(moduleStruct, 'loadModuleData');
 
     % --- Extract shared time vector ---
     X = moduleStruct.(datenumField);
diff --git a/libs/SensorThreshold/loadModuleMetadata.m b/libs/SensorThreshold/loadModuleMetadata.m
@@ -6,8 +6,9 @@
 %   whose ThresholdRules reference matching state keys.
 %
 %   metadataStruct must have the same format as module data: fields +
-%   doc.date naming the datenum field. State signals can be numeric
-%   arrays or cell arrays of char.
+%   .doc with per-field .name/.datum entries. The .datum value names the
+%   shared datenum field. State signals can be numeric arrays or cell
+%   arrays of char.
 %
 %   ThresholdRules must be attached to sensors before calling this
 %   function. Sensors with no rules are skipped. Rules with empty
@@ -24,29 +25,8 @@
 
     narginchk(2, 2);
 
-    % --- Validate doc metadata (same pattern as loadModuleData) ---
-    if ~isfield(metadataStruct, 'doc')
-        error('loadModuleMetadata:missingDoc', ...
-            'Metadata struct must contain a ''doc'' field.');
-    end
-    if ~isfield(metadataStruct.doc, 'date')
-        error('loadModuleMetadata:missingDocDate', ...
-            'Metadata struct .doc must contain a ''date'' field naming the datenum variable.');
-    end
-
-    datenumField = metadataStruct.doc.date;
-
-    if ~ischar(datenumField)
-        error('loadModuleMetadata:invalidDocDate', ...
-            'Metadata struct .doc.date must be a char (field name), got %s.', ...
-            class(datenumField));
-    end
-
-    if ~isfield(metadataStruct, datenumField)
-        error('loadModuleMetadata:missingDatenum', ...
-            'Datenum field ''%s'' (from doc.date) not found in metadata struct.', ...
-            datenumField);
-    end
+    % --- Extract datenum field name from doc metadata ---
+    datenumField = extractDatenumField(metadataStruct, 'loadModuleMetadata');
 
     % --- Early exit for empty sensors ---
     if isempty(sensors)
diff --git a/libs/SensorThreshold/private/extractDatenumField.m b/libs/SensorThreshold/private/extractDatenumField.m
@@ -0,0 +1,47 @@
+function datenumField = extractDatenumField(moduleStruct, callerName)
+%EXTRACTDATENUMFIELD Extract the datenum field name from a module struct.
+%   datenumField = extractDatenumField(moduleStruct, callerName) reads the
+%   .doc metadata to find the shared datenum field name. The .doc struct
+%   contains one sub-field per data field, each with .name and .datum
+%   properties. The .datum value names the datenum field.
+%
+%   callerName is used in error identifiers for clear diagnostics.
+%
+%   See also loadModuleData, loadModuleMetadata.
+
+    if ~isfield(moduleStruct, 'doc')
+        error([callerName ':missingDoc'], ...
+            'Module struct must contain a ''doc'' field.');
+    end
+
+    doc = moduleStruct.doc;
+    docFields = fieldnames(doc);
+
+    if isempty(docFields)
+        error([callerName ':emptyDoc'], ...
+            'Module struct .doc has no fields.');
+    end
+
+    % Read .datum from the first doc entry
+    firstEntry = doc.(docFields{1});
+
+    if ~isstruct(firstEntry) || ~isfield(firstEntry, 'datum')
+        error([callerName ':missingDatum'], ...
+            'Module struct .doc.%s must be a struct with a ''datum'' field.', ...
+            docFields{1});
+    end
+
+    datenumField = firstEntry.datum;
+
+    if ~ischar(datenumField)
+        error([callerName ':invalidDatum'], ...
+            'Module struct .doc.%s.datum must be a char (field name), got %s.', ...
+            docFields{1}, class(datenumField));
+    end
+
+    if ~isfield(moduleStruct, datenumField)
+        error([callerName ':missingDatenum'], ...
+            'Datenum field ''%s'' (from doc.%s.datum) not found in module struct.', ...
+            datenumField, docFields{1});
+    end
+end
diff --git a/tests/suite/TestLoadModuleData.m b/tests/suite/TestLoadModuleData.m
@@ -10,10 +10,11 @@ function addPaths(testCase)
     methods (Static)
         function ms = makeModuleStruct(sensorKeys, nPoints)
             %MAKEMODULESTRUCT Build a fake module struct for testing.
-            ms.doc.date = 'time_utc';
             ms.time_utc = linspace(datenum(2024,1,1), datenum(2024,1,2), nPoints);
             for i = 1:numel(sensorKeys)
                 ms.(sensorKeys{i}) = randn(1, nPoints);
+                ms.doc.(sensorKeys{i}).name = sensorKeys{i};
+                ms.doc.(sensorKeys{i}).datum = 'time_utc';
             end
         end
     end
@@ -102,8 +103,8 @@ function testDocFieldExcluded(testCase)
             reg.register('doc', Sensor('doc'));
             reg.register('temp', Sensor('temp'));
 
-            % Manually build struct so 'doc' is a data field that also has .date
-            ms.doc.date = 'time_utc';
+            ms.doc.temp.name = 'Temperature';
+            ms.doc.temp.datum = 'time_utc';
             ms.time_utc = linspace(datenum(2024,1,1), datenum(2024,1,2), 50);
             ms.temp = randn(1, 50);
             sensors = loadModuleData(reg, ms);
@@ -137,21 +138,25 @@ function testMissingDocFieldErrors(testCase)
             testCase.verifyTrue(threw, 'missing_doc_throws');
         end
 
-        function testMissingDocDateErrors(testCase)
+        function testDocMissingDatumErrors(testCase)
+            % doc entry without .datum field
             reg = ExternalSensorRegistry('Test');
-            ms = struct('doc', struct('version', '1.0'), 'temp', [1 2 3]);
+            ms.doc.temp.name = 'Temperature';  % no .datum
+            ms.temp = [1 2 3];
             threw = false;
             try
                 loadModuleData(reg, ms);
             catch
                 threw = true;
             end
-            testCase.verifyTrue(threw, 'missing_doc_date_throws');
+            testCase.verifyTrue(threw, 'missing_datum_throws');
         end
 
         function testDatenumFieldNotInStructErrors(testCase)
             reg = ExternalSensorRegistry('Test');
-            ms = struct('doc', struct('date', 'nonexistent'), 'temp', [1 2 3]);
+            ms.doc.temp.name = 'Temperature';
+            ms.doc.temp.datum = 'nonexistent';
+            ms.temp = [1 2 3];
             threw = false;
             try
                 loadModuleData(reg, ms);
@@ -161,17 +166,19 @@ function testDatenumFieldNotInStructErrors(testCase)
             testCase.verifyTrue(threw, 'bad_datenum_ref_throws');
         end
 
-        function testDocDateNotCharErrors(testCase)
-            % Defensive test beyond spec scope: validates doc.date type
+        function testDatumNotCharErrors(testCase)
+            % Defensive test: validates datum type
             reg = ExternalSensorRegistry('Test');
-            ms = struct('doc', struct('date', 42), 'temp', [1 2 3]);
+            ms.doc.temp.name = 'Temperature';
+            ms.doc.temp.datum = 42;
+            ms.temp = [1 2 3];
             threw = false;
             try
                 loadModuleData(reg, ms);
             catch
                 threw = true;
             end
-            testCase.verifyTrue(threw, 'non_char_date_throws');
+            testCase.verifyTrue(threw, 'non_char_datum_throws');
         end
 
         function testOutputIsRowCell(testCase)
diff --git a/tests/suite/TestLoadModuleMetadata.m b/tests/suite/TestLoadModuleMetadata.m
@@ -10,10 +10,11 @@ function addPaths(testCase)
     methods (Static)
         function ms = makeMetadataStruct(stateKeys, nPoints)
             %MAKEMETADATASTRUCT Build a fake metadata struct for testing.
-            ms.doc.date = 'time_utc';
             ms.time_utc = linspace(datenum(2024,1,1), datenum(2024,1,2), nPoints);
             for i = 1:numel(stateKeys)
                 ms.(stateKeys{i}) = zeros(1, nPoints);
+                ms.doc.(stateKeys{i}).name = stateKeys{i};
+                ms.doc.(stateKeys{i}).datum = 'time_utc';
             end
         end
 
@@ -53,7 +54,8 @@ function testCellStringState(testCase)
             s = TestLoadModuleMetadata.makeSensorWithRule( ...
                 'temp', struct('recipe', 'bake'), 80);
 
-            ms.doc.date = 'time_utc';
+            ms.doc.recipe.name = 'recipe';
+            ms.doc.recipe.datum = 'time_utc';
             ms.time_utc = linspace(datenum(2024,1,1), datenum(2024,1,2), 6);
             ms.recipe = {'idle', 'idle', 'bake', 'bake', 'bake', 'idle'};
 
@@ -156,7 +158,8 @@ function testSinglePointMetadata(testCase)
             s = TestLoadModuleMetadata.makeSensorWithRule( ...
                 'temp', struct('machine', 1), 50);
 
-            ms.doc.date = 'time_utc';
+            ms.doc.machine.name = 'machine';
+            ms.doc.machine.datum = 'time_utc';
             ms.time_utc = datenum(2024,1,1);
             ms.machine = 1;
 
@@ -172,7 +175,8 @@ function testColumnVectorInputs(testCase)
             s = TestLoadModuleMetadata.makeSensorWithRule( ...
                 'temp', struct('machine', 1), 50);
 
-            ms.doc.date = 'time_utc';
+            ms.doc.machine.name = 'machine';
+            ms.doc.machine.datum = 'time_utc';
             ms.time_utc = linspace(datenum(2024,1,1), datenum(2024,1,2), 6)';
             ms.machine = [0; 0; 1; 1; 0; 0];
 
@@ -200,20 +204,23 @@ function testMissingDocErrors(testCase)
             testCase.verifyTrue(threw, 'missing_doc_throws');
         end
 
-        function testMissingDocDateErrors(testCase)
-            ms = struct('doc', struct('version', '1.0'), 'machine', [1 2 3]);
+        function testDocMissingDatumErrors(testCase)
+            % doc entry without .datum field
+            ms.doc.machine.name = 'machine';  % no .datum
+            ms.machine = [1 2 3];
             threw = false;
             try
                 loadModuleMetadata(ms, {});
             catch
                 threw = true;
             end
-            testCase.verifyTrue(threw, 'missing_doc_date_throws');
+            testCase.verifyTrue(threw, 'missing_datum_throws');
         end
 
-        function testDocDateNotInStructErrors(testCase)
-            ms = struct('doc', struct('date', 'nonexistent'), ...
-                'machine', [1 2 3]);
+        function testDatenumFieldNotInStructErrors(testCase)
+            ms.doc.machine.name = 'machine';
+            ms.doc.machine.datum = 'nonexistent';
+            ms.machine = [1 2 3];
             threw = false;
             try
                 loadModuleMetadata(ms, {});
@@ -223,16 +230,18 @@ function testDocDateNotInStructErrors(testCase)
             testCase.verifyTrue(threw, 'bad_datenum_ref_throws');
         end
 
-        function testDocDateNotCharErrors(testCase)
-            % Defensive test beyond spec scope
-            ms = struct('doc', struct('date', 42), 'machine', [1 2 3]);
+        function testDatumNotCharErrors(testCase)
+            % Defensive test: validates datum type
+            ms.doc.machine.name = 'machine';
+            ms.doc.machine.datum = 42;
+            ms.machine = [1 2 3];
             threw = false;
             try
                 loadModuleMetadata(ms, {});
             catch
                 threw = true;
             end
-            testCase.verifyTrue(threw, 'non_char_date_throws');
+            testCase.verifyTrue(threw, 'non_char_datum_throws');
         end
 
         function testOutputRowOrientation(testCase)
