[matlab] Add docstrings to the remaining main classes/functions

matlab/Segment.m

@@ -1,4 +1,23 @@
 classdef Segment
+    % SEGMENT  Describes a segment of time in a source for a trial, optionally with
+    % additional conditions specific to that segment of time. The conditions for the whole
+    % trial will be combined with any conditions specific to the segment (so that all
+    % conditions applicable to that segment of time will be available in one spot).
+    %
+    %   seg = Segment(trial, source)
+    %   seg = Segment(trial, source, Name, Value)
+    %
+    % # Input arguments
+    %
+    % - `source`: Can be an instance of a Source class subtype, or the name of a source
+    %   known/expected to be present in `trial`.
+    %
+    % # Name-Value arguments
+    %
+    % - `'Start'`: The beginning time of the segment
+    % - `'Finish'`: The ending time of the segment
+    % - `'Conditions'`: A struct containing any additional conditions for that segment.
+
     properties
         trial (1,1) Trial
         source (1,1) Source
@@ -30,6 +49,13 @@
         end
 
         function data = readsegment(obj, varargin)
+            % READSEGMENT  Read the segment of time from the source of `seg`. Name-value
+            % arguments (besides `'Start'` and `'Finish'`, which are reserved) are passed on
+            % to the `readsource` method for the segment's `src` class.
+            %
+            %   data = readsegment(seg)
+            %   data = readsegment(seg, Name, Value)
+
             data = readsource(obj.source, 'Start', obj.start, 'Finish', obj.finish, varargin{:});
         end
 

matlab/SegmentResult.m

@@ -1,4 +1,15 @@
 classdef SegmentResult
+    % SEGMENTRESULT  Contains a segment and the results of an analysis.
+    %
+    %   segres = SegmentResult(seg)
+    %   segres = SegmentResult(seg, results)
+    %
+    % # Input arguments
+    %
+    % - `seg`: A Segment
+    % - `results`: (Optional) A struct where each field is an individual result. If omitted,
+    % an empty struct will be created.
+
     properties
         segment Segment
         results

matlab/Source.m

@@ -113,16 +113,51 @@ function readsource(obj)
                 class(obj))
         end
 
-        function generatesource(obj)
+        function generatesource(obj, trial, deps, varargin)
+            % GENERATESOURCE  Generate a source `src` for `trial` using the dependent
+            % sources `deps`. Returns a source of the same class as `src`, but is not
+            % required to be exactly equal to `src` (i.e. a different `src.path`).
+            %
+            %   newsrc = generatesource(src, trial, deps)
+            %   newsrc = generatesource(src, trial, deps, Name, Value)
+            %
+            % # Input arguments
+            %
+            % - `src`: A source that may or may not exist yet (e.g. if `'Force'` was set to
+            %   true in `requiresource`).
+            % - `trial`: The trial that `src`/`newsrc` is being generated for/from.
+            % - `deps`: The sources that `src` depends on to be generated (i.e. sources
+            %   which contain data which is used to generate the data comprising `newsrc`)
+            %
+            % # Name-Value arguments
+            %
+            % Any name-value arguments will be specific to a particular Source class
+            % subtype. **N.B.**: `generatesource` will normally be called by
+            % `requiresource`, which uses name-value arguments `'Name'`, `'Force'`, and
+            % `'Dependencies'`. These names are functionally reserved (i.e. not available
+            % for use in `generatesource` methods), as they will not be passed on to
+            % `generatesource` by `requiresource`.
+
             error('Error: A `generatesource` function has not been implemented yet for %s', ...
                 class(obj))
         end
 
         function deps = dependencies(obj)
+            % DEPENDENCIES  Get the sources that `src` depends on to be generated with
+            % `generatesource`. By default sources are assumed not to be automatically
+            % generatable, therefore `dependencies` returns false unless a `dependencies`
+            % method has been created for a specific class subtyping `Source`.
+            %
+            %   deps = dependencies(src)
+
             deps = false;
         end
 
         function name = srcname_default(obj)
+            % SRCNAME_DEFAULT  Get the default name for a source of a given `< Source` class
+            %
+            %   name = srcname_default(src)
+
             name = class(obj);
         end
 

matlab/Trial.m

@@ -103,6 +103,22 @@ function requiresource(trial, src, varargin)
             %   requiresource(trial, src)
             %   requiresource(trial, src, Name, Value)
             %
+            % # Name-Value arguments
+            %
+            % - `'Name'`: The name to use if the `src` is missing and needs to be generated.
+            %   Defaults to the `srcname_default(src)`.
+            % - `'Force'`: (Re)generate the `src`, even if it already exists.
+            % - `'Dependencies'`: The sources that `src` depends on to be generated.
+            %   Defaults to `dependencies(src)`, which will be empty if the `src` class has
+            %   not defined a `dependencies` method.
+            % - Any remaining unmatched name-value arguments will be passed on to
+            %   `generatesource` (if called).
+            %
+            % # Examples
+            %
+            % ```matlab
+            % requiresource(trial, GaitEvents(), 'Dependencies', {C3DSource()})
+            % ```
 
             p = inputParser;
             p.KeepUnmatched = true;