[Matlab] Add basic nix.MetadataMixIn doc

Author: mpsonntag

+nix/Block.m

@@ -20,7 +20,6 @@
 %   sources      access to all first level nix.Source child entities.
 %   tags         access to all nix.Tag child entities.
 %   multiTags    access to all nix.MultiTag child entities.
-%   sections     access to all first level nix.Section child entities.
 %
 % See also nix.DataArray, nix.Source, nix.Group, nix.Tag, nix.MultiTag, nix.Section.
 %

+nix/DataArray.m

@@ -47,7 +47,6 @@
 % nix.DataArray dynamic child entity properties:
 %   dimensions   access to all dimensions associated with a DataArray.
 %   sources      access to all first level nix.Source child entities.
-%   sections     access to all first level nix.Section child entities.
 %
 % See also nix.Source, nix.Section.
 %

+nix/Group.m

@@ -20,7 +20,6 @@
 %   tags         access to all nix.Tag child entities.
 %   multiTags    access to all nix.MultiTag child entities.
 %   sources      access to all first level nix.Source child entities.
-%   sections     access to all first level nix.Section child entities.
 %
 % See also nix.DataArray, nix.Tag, nix.MultiTag, nix.Source, nix.Section.
 %

+nix/MetadataMixIn.m

@@ -1,3 +1,17 @@
+% Mixin Class for entities that can be associated with additional metadata.
+%
+% The data part of the NIX data model consists of six main elements which all inherit 
+% from the MetadataMixin Class: nix.Block, nix.Group, nix.DataArray, nix.Tag,
+% nix.MultiTag and nix.Source.
+% Common to all those entities is an optional property sections which  provides a link 
+% to one nix.Section entity and therefore makes it possible to annotate the entities 
+% with additional metadata.
+%
+% Depends on nix.Entity.
+%
+% See also nix.Section, nix.Block, nix.Group, nix.DataArray, nix.Tag, nix.MultiTag, nix.Source, nix.Entity.
+%
+%
 % Copyright (c) 2016, German Neuroinformatics Node (G-Node)
 %
 % All rights reserved.
@@ -7,26 +21,49 @@
 % LICENSE file in the root of the Project.
 
 classdef MetadataMixIn < handle
-    %MetadataMixIn
-    % mixin class for nix entities with metadata
-    % depends on 
-    % - nix.Entity
 
     properties (Abstract, Hidden)
         alias
     end
 
     methods
         function r = openMetadata(obj)
+            % Retrieves the referenced nix.Section from the invoking nix.Entity.
+            %
+            % Returns:  (nix.Section) The Section or an empty cell, 
+            %                       if the Section was not found.
+            %
+            % Example:  getSec = currEntity.openMetadata();
+            %
+            % See also nix.Section.
+
             r = nix.Utils.fetchObj(obj, 'openMetadataSection', @nix.Section);
         end
 
-        function [] = setMetadata(obj, val)
-            if (isempty(val))
+        function [] = setMetadata(obj, idEntity)
+            % Set a nix.Section as metadata of the invoking nix.Entity.
+            %
+            % If metadata was already set, using this method again will
+            % replace the reference to the previous Section with a reference
+            % to the provided Section.
+            %
+            % The link to a Section can be removed by handing an empty string 
+            % to the method. The referenced Section itself will not be removed.
+            %
+            % idEntity (char/nix.Section):  The id of an existing Section,
+            %                                 or a valid nix.Section entity.
+            %
+            % Example:  currEntity.setMetadata('some-section-id');
+            %           currEntity.setMetadata(currFile.sections{1});
+            %           currEntity.setMetadata(''); % remove reference to section
+            %
+            % See also nix.Section.
+
+            if (isempty(idEntity))
                 fname = strcat(obj.alias, '::setNoneMetadata');
-                nix_mx(fname, obj.nixhandle, val);
+                nix_mx(fname, obj.nixhandle, idEntity);
             else
-                nix.Utils.addEntity(obj, 'setMetadata', val, 'nix.Section');
+                nix.Utils.addEntity(obj, 'setMetadata', idEntity, 'nix.Section');
             end
         end
     end

+nix/MultiTag.m

@@ -32,7 +32,6 @@
 %   references   access to all nix.DataArray child entities referenced by the MultiTag.
 %   features     access to all nix.Features child entities referenced by the MultiTag.
 %   sources      access to all first level nix.Source child entities.
-%   sections     access to all first level nix.Section child entities.
 %
 % See also nix.DataArray, nix.Feature, nix.Source, nix.Section.
 %
@@ -487,7 +486,7 @@
         end
 
         function [] = setExtents(obj, idNameEntity)
-            % Set a nix.DataArray as the extents data of the invoking Tag.
+            % Set a nix.DataArray as the extents data of the invoking MultiTag.
             %
             % If extents were already set, using this method again will
             % replace the reference to the old DataArray with a reference

+nix/Tag.m

@@ -37,7 +37,6 @@
 %   references   access to all nix.DataArray child entities referenced by the Tag.
 %   features     access to all nix.Features child entities referenced by the Tag.
 %   sources      access to all first level nix.Source child entities.
-%   sections     access to all first level nix.Section child entities.
 %
 % See also nix.DataArray, nix.Feature, nix.Source, nix.Section.
 %