Skip to content

Commit e6832d7

Browse files
mpsonntagmpsonntag
committed
[Matlab] Add basic nix.Section documentation
- documentation for the Section entity. - simplifies the Section.deleteProperty method.
1 parent d5e814b commit e6832d7

File tree

5 files changed

+494
-118
lines changed

5 files changed

+494
-118
lines changed

‎+nix/File.m‎

Lines changed: 39 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,9 @@
1111
% blocks access to all nix.Block child entities.
1212
% sections access to all first level nix.Section child entities.
1313
%
14+
% Example opening a NIX file:
15+
% getFileAccess = nix.File('/path/to/file', nix.FileMode.ReadWrite);
16+
%
1417
% See also nix.Block, nix.Section.
1518
%
1619
%
@@ -32,12 +35,14 @@
3235
function obj = File(path, mode)
3336
% File constructor used to open or create a nix.File.
3437
%
35-
% path (char): path to a file to open or create.
36-
% mode (char): requires a valid nix.FileMode. Defaults to
37-
% nix.FileMode.ReadWrite if no FileMode is provided.
38+
% path (char): Path to a file to open or create.
39+
% mode (char): Requires a valid nix.FileMode. Defaults to
40+
% nix.FileMode.ReadWrite if no FileMode is provided.
3841
%
3942
% Returns: (nix.File).
4043
%
44+
% Example: getFileAccess = nix.File('/path/to/file', nix.FileMode.ReadWrite);
45+
%
4146
% See also nix.FileMode.
4247

4348
if (~exist('mode', 'var'))
@@ -56,6 +61,8 @@
5661
% Check if the file is currently open.
5762
%
5863
% Returns: (logical) True if the file is open, False otherwise.
64+
%
65+
% Example: check = currFile.isOpen();
5966

6067
fname = strcat(obj.alias, '::isOpen');
6168
r = nix_mx(fname, obj.nixhandle);
@@ -66,6 +73,8 @@
6673
%
6774
% Returns: (nix.FileMode).
6875
%
76+
% Example: getFileMode = currFile.fileMode();
77+
%
6978
% See also nix.FileMode.
7079

7180
fname = strcat(obj.alias, '::fileMode');
@@ -79,6 +88,8 @@
7988
% offending entities.
8089
%
8190
% Returns: (struct) Custom warning/error struct.
91+
%
92+
% Example: checkFile = currFile.validate();
8293

8394
fname = strcat(obj.alias, '::validate');
8495
r = nix_mx(fname, obj.nixhandle);
@@ -91,16 +102,14 @@
91102
function r = createBlock(obj, name, type)
92103
% Create a new nix.Block entity, that is immediately persisted to the file.
93104
%
94-
% name (char): the name of the Block, has to be unique within the file.
95-
% read only Block property.
96-
% type (char): the type of the Block, required.
97-
% Type can be used to give semantic meaning to an entity
98-
% and expose it to search methods in a broader context.
99-
% read/write Block property.
105+
% name (char): The name of the Block, has to be unique within the file.
106+
% type (char): The type of the Block, required.
107+
% Type can be used to give semantic meaning to an entity
108+
% and expose it to search methods in a broader context.
100109
%
101-
% Returns: (nix.Block) The newly created Block.
110+
% Returns: (nix.Block) The newly created Block.
102111
%
103-
% Example: newBlock = f.createBlock('trial1', 'ephys');
112+
% Example: newBlock = f.createBlock('trial1', 'ephys');
104113
%
105114
% See also nix.Block.
106115

@@ -174,7 +183,7 @@
174183
% will be deleted from the file as well.
175184
%
176185
% idNameEntity (char/nix.Block): Name or id of the entity to
177-
% be deleted or the entity itself.
186+
% be deleted or the entity itself.
178187
%
179188
% Returns: (logical) True if the Block has been removed, false otherwise.
180189
%
@@ -190,14 +199,14 @@
190199
function r = filterBlocks(obj, filter, val)
191200
% Get a filtered cell array of all Blocks within this file.
192201
%
193-
% filter (nix.Filter): the nix.Filter to be applied. Supports
194-
% the filters 'acceptall', 'id', 'ids',
202+
% filter (nix.Filter): The nix.Filter to be applied. Supports
203+
% The filters 'acceptall', 'id', 'ids',
195204
% 'name' and 'type'.
196205
% val (char): Value that is applied with the selected
197206
% filter.
198207
%
199208
% Returns: ([nix.Block]) A cell array of Blocks filtered according
200-
% to the applied nix.Filter.
209+
% to the applied nix.Filter.
201210
%
202211
% Example: getBlocks = f.filterBlocks(nix.Filter.type, 'ephys');
203212
%
@@ -213,16 +222,14 @@
213222
function r = createSection(obj, name, type)
214223
% Create a new nix.Section entity, that is immediately persisted to the file.
215224
%
216-
% name (char): the name of the Section, has to be unique within the file.
217-
% read only Section property.
218-
% type (char): the type of the Section, required.
219-
% Type can be used to give semantic meaning to an entity
220-
% and expose it to search methods in a broader context.
221-
% read/write Section property.
225+
% name (char): The name of the Section, has to be unique within the file.
226+
% type (char): The type of the Section, required.
227+
% Type can be used to give semantic meaning to an entity
228+
% and expose it to search methods in a broader context.
222229
%
223-
% Returns: (nix.Section) The newly created Section.
230+
% Returns: (nix.Section) The newly created Section.
224231
%
225-
% Example: newSec = f.createSection('settings1', 'ephys');
232+
% Example: newSec = f.createSection('settings1', 'ephys');
226233
%
227234
% See also nix.Section.
228235

@@ -232,9 +239,9 @@
232239
end
233240

234241
function r = sectionCount(obj)
235-
% Get the number of root Sections in the file.
242+
% Get the number of direct child Sections in the file.
236243
%
237-
% Returns: (uint) The number of root (non nested) Sections.
244+
% Returns: (uint) The number of direct child (non nested) Sections.
238245
%
239246
% Example: sc = f.sectionCount();
240247
%
@@ -264,7 +271,7 @@
264271
% idName (char): Name or ID of the Section.
265272
%
266273
% Returns: (nix.Section) The nix.Section or an empty cell,
267-
% if the Section was not found.
274+
% if the Section was not found.
268275
%
269276
% Example: getSec = f.openSection('23bb8a99-1812-4bc6-a52c-45e96864756b');
270277
% getSec = f.openSection('settings1');
@@ -275,7 +282,7 @@
275282
end
276283

277284
function r = openSectionIdx(obj, index)
278-
% Retrieves an existing Section from the file, accessed by index.
285+
% Retrieves an Section from the file, accessed by index.
279286
%
280287
% index (double): The index of the Section to read.
281288
%
@@ -312,8 +319,8 @@
312319
function r = filterSections(obj, filter, val)
313320
% Get a filtered cell array of all root Sections within this file.
314321
%
315-
% filter (nix.Filter): the nix.Filter to be applied. Supports
316-
% the filters 'acceptall', 'id', 'ids',
322+
% filter (nix.Filter): The nix.Filter to be applied. Supports
323+
% The filters 'acceptall', 'id', 'ids',
317324
% 'name' and 'type'.
318325
% val (char): Value that is applied with the selected
319326
% filter.
@@ -357,11 +364,9 @@
357364
%
358365
% maxDepth (double): The maximum depth of traversal to retrieve nested
359366
% Sections. Should be handled like an index.
360-
% filter (nix.Filter): the nix.Filter to be applied. Supports
361-
% the filters 'acceptall', 'id', 'ids',
362-
% 'name' and 'type'.
363-
% val (char): Value that is applied with the selected
364-
% filter.
367+
% filter (nix.Filter): The nix.Filter to be applied. Supports the filters
368+
% 'acceptall', 'id', 'ids', 'name' and 'type'.
369+
% val (char): Value that is applied with the selected filter.
365370
%
366371
% Example: allSec = f.filterFindSections(2, nix.Filter.type, 'ephys');
367372
%

‎+nix/MetadataMixIn.m‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@
3131
% Retrieves the referenced nix.Section from the invoking nix.Entity.
3232
%
3333
% Returns: (nix.Section) The Section or an empty cell,
34-
% if the Section was not found.
34+
% if no Section was referenced.
3535
%
3636
% Example: getSec = currEntity.openMetadata();
3737
%
@@ -55,7 +55,7 @@
5555
%
5656
% Example: currEntity.setMetadata('some-section-id');
5757
% currEntity.setMetadata(currFile.sections{1});
58-
% currEntity.setMetadata(''); % remove reference to section
58+
% currEntity.setMetadata(''); %-- remove reference to Section.
5959
%
6060
% See also nix.Section.
6161

0 commit comments

Comments
 (0)