Update main function docstrings to work better with sphinx/rst format…

…ting Add "sections" Specify input and output arguments Reformat examples
NeurodataWithoutBorders · Dec 6, 2024 · 09d464c · 09d464c
1 parent 42e9995
commit 09d464c
Show file tree

Hide file tree

Showing 6 changed files with 207 additions and 90 deletions.
diff --git a/NwbFile.m b/NwbFile.m
@@ -1,18 +1,23 @@
 classdef NwbFile < types.core.NWBFile
-    % NWBFILE Root object representing data read from an NWB file.
-    %
-    % Requires that core and extension NWB types have been generated
-    % and reside in a 'types' package on the matlab path.
-    %
-    % Example. Construct an object from scratch for export:
-    %    nwb = NwbFile;
-    %    nwb.epochs = types.core.Epochs;
-    %    nwbExport(nwb, 'epoch.nwb');
-    %
-    % See also NWBREAD, GENERATECORE, GENERATEEXTENSION
+% NWBFILE - Root object representing an NWB file.
+%
+% Requires that core and extension NWB types have been generated
+% and reside in a ``+types`` namespace on the MATLAB search path.
+%
+% Usage:
+%  Example 1 - Construct a simple NwbFile object for export::
+%
+%    nwb = NwbFile;
+%    nwb.epochs = types.core.Epochs;
+%    nwbExport(nwb, 'epoch.nwb');
+%
+% See also:
+%   nwbRead, generateCore, generateExtension
 
     methods
         function obj = NwbFile(propValues)
+        % NWBFILE - Create an NWB File object
+
             arguments
                 propValues.?types.core.NWBFile
                 propValues.nwb_version
@@ -26,7 +31,7 @@
         end
 
         function export(obj, filename, mode)
-        % export - Export NWB file object
+        % EXPORT - Export NWB file object
 
             arguments
                 obj (1,1) NwbFile
@@ -98,10 +103,14 @@ function export(obj, filename, mode)
         end
 
         function objectMap = searchFor(obj, typename, varargin)
-            % Searches this NwbFile object for a given typename
+            % searchFor - Search for for a given typename within the NwbFile object
+            %
             % Including the full namespace is optional.
-            % WARNING: The returned paths are resolvable but do not necessarily
-            % indicate a real HDF5 path. Their only function is to be resolvable.
+            %
+            % .. warning:: 
+            %   The returned paths are resolvable but do not necessarily
+            %   indicate a real HDF5 path. Their only function is to be resolvable.
+
             objectMap = searchProperties(...
                 containers.Map,...
                 obj,...

diff --git a/generateCore.m b/generateCore.m
@@ -1,27 +1,40 @@
 function generateCore(version, options)
-    % GENERATECORE Generate Matlab classes from NWB core schema files
-    %   GENERATECORE()  Generate classes (Matlab m-files) from the
-    %   NWB core namespace file. By default, generates off of the most recent nwb-schema
-    %   release.
-    %
-    %   GENERATECORE(version)  Generate classes for the
-    %   core namespace of the listed version.
-    %
-    %   A cache of schema data is generated in the 'namespaces' subdirectory in
-    %   the current working directory.  This is for allowing cross-referencing
-    %   classes between multiple namespaces.
-    %
-    %   Output files are generated placed in a '+types' subdirectory in the
-    %   current working directory.
-    %
-    %   GENERATECORE(__, 'savedir', saveDirectory) Generates the core class
-    %   files in the specified directory.
-    %
-    %   Example:
-    %      generateCore();
-    %      generateCore('2.2.3');
-    %
-    %   See also GENERATEEXTENSION
+% GENERATECORE - Generate Matlab classes from NWB core schema files
+%
+% Syntax:
+%   GENERATECORE() Generate classes (Matlab m-files) from the
+%   NWB core namespace file. By default, generates off of the most recent 
+%   nwb-schema release.
+%
+%   GENERATECORE(version)  Generate classes for the
+%   core namespace of the listed version.
+%
+%   GENERATECORE(__, Name, Value)  Generate classes based on optional 
+%   name-value pairs controlling the output .
+%
+%   A cache of schema data is generated in the ``namespaces`` subdirectory in
+%   the matnwb root directory.  This is for allowing cross-referencing
+%   classes between multiple namespaces.
+%
+%   Output files are placed in a ``+types`` subdirectory in the
+%   matnwb root directory directory.
+%
+% Usage:
+%  Example 1 - Generate core schemas for the latest version of NWB::
+%
+%    generateCore();
+%
+%  Example 2 - Generate core schemas for an older version of NWB::
+%
+%     generateCore('2.2.3');
+%
+%  Example 3 - Generate and save classes in a custom location::
+%
+%     %  Generates the core class files in the specified directory.
+%     generateCore('savedir', saveDirectory)
+%
+% See also:
+%   generateExtension
 
     arguments
         version (1,1) string {matnwb.common.mustBeValidSchemaVersion} = "latest"

diff --git a/generateExtension.m b/generateExtension.m
@@ -1,22 +1,37 @@
 function generateExtension(namespaceFilePath, options)
-    % GENERATEEXTENSION Generate Matlab classes from NWB extension schema file
-    %   GENERATEEXTENSION(extension_path...)  Generate classes
-    %   (Matlab m-files) from one or more NWB schema extension namespace
-    %   files.  A registry of already generated core types is used to resolve
-    %   dependent types.
-    %
-    %   A cache of schema data is generated in the 'namespaces' subdirectory in
-    %   the current working directory.  This is for allowing cross-referencing
-    %   classes between multiple namespaces.
-    %
-    %   Output files are generated placed in a '+types' subdirectory in the
-    %   current working directory.
-    %
-    %   Example:
-    %      generateExtension('schema\myext\myextension.namespace.yaml', 'schema\myext2\myext2.namespace.yaml');
-    %
-    %   See also GENERATECORE
-
+% GENERATEEXTENSION - Generate Matlab classes from NWB extension schema file
+%
+% Syntax:
+%   GENERATEEXTENSION(extension_path...) Generate classes (Matlab m-files) 
+%   from one or more NWB schema extension namespace files. A registry of 
+%   already generated core types is used to resolve dependent types.
+%
+%   A cache of schema data is generated in the ``namespaces`` subdirectory in
+%   the matnwb root directory.  This is for allowing cross-referencing
+%   classes between multiple namespaces.
+%
+%   Output files are placed in a ``+types`` subdirectory in the
+%   matnwb root directory directory.
+%
+% Input Arguments:
+%  - namespaceFilePath (string) - 
+%    Filepath pointing to a schema extension namespace file. This is a
+%    repeating argument, so multiple filepaths can be provided
+% 
+%  - options (name-value pairs) -
+%    Optional name-value pairs. Available options:
+%  
+%    - savedir (string) -
+%      A folder to save generated classes for NWB/extension types.
+%
+% Usage:
+%  Example 1 - Generate classes for custom schema extensions::
+%
+%    generateExtension('schema\myext\myextension.namespace.yaml', 'schema\myext2\myext2.namespace.yaml');
+%
+% See also:
+%   generateCore
+
     arguments (Repeating)
         namespaceFilePath (1,1) string {mustBeYamlFile}
     end

diff --git a/nwbClearGenerated.m b/nwbClearGenerated.m
@@ -1,9 +1,35 @@
 function clearedNamespaceNames = nwbClearGenerated(targetFolder, options)
-    %% NWBCLEARGENERATED clears generated class files.
+% NWBCLEARGENERATED - Clear generated class files.
+%
+% Syntax:
+%   NWBCLEARGENERATED() Clear generated class files from the ``+types`` 
+%   folder in the matnwb root directory.
+%
+% Input Arguments:
+%  - targetFolder (string) - 
+%    Path name for folder containing generated classes in a ``+types``
+%    namespace folder. Default value is the matnwb root directory
+% 
+%  - options (name-value pairs) -
+%    Optional name-value pairs. Available options:
+%  
+%    - ClearCache (logical) -
+%      Whether to clear the cached schema data in the ``namespaces`` folder.
+%      Default is ``false``
+%
+% Usage:
+%  Example 1 - Clear all generated classes in the matnwb root directory::
+%
+%    nwbClearGenerated();
+%
+% See also:
+%   generateCore, generateExtension
+
     arguments
         targetFolder (1,1) string  {mustBeFolder} = misc.getMatnwbDir()
         options.ClearCache (1,1) logical = false
     end
+
     typesPath = fullfile(targetFolder, '+types');
     listing = dir(typesPath);
     moduleNames = setdiff({listing.name}, {'+untyped', '+util', '.', '..'});
@@ -26,4 +52,4 @@
         clearedNamespaceNames = strrep(clearedNamespaceNames, '+', '');
         clearedNamespaceNames = string(clearedNamespaceNames);
     end
-end
+end
diff --git a/nwbExport.m b/nwbExport.m
@@ -1,19 +1,41 @@
 function nwbExport(nwbFileObjects, filePaths, mode)
-    %NWBEXPORT Writes an NWB file.
-    %  nwbRead(nwb, filename) Writes the nwb object to a file at filename.
-    %
-    %  Example:
-    %    % Generate Matlab code for the NWB objects from the core schema.
-    %    % This only needs to be done once.
-    %    generateCore('schema\core\nwb.namespace.yaml');
-    %    % Create some fake fata and write
-    %    nwb = NwbFile;
-    %    nwb.session_start_time = datetime('now');
-    %    nwb.identifier = 'EMPTY';
-    %    nwb.session_description = 'empty test file';
-    %    nwbExport(nwb, 'empty.nwb');
-    %
-    %  See also GENERATECORE, GENERATEEXTENSION, NWBFILE, NWBREAD
+%NWBEXPORT - Writes an NWB file.
+%
+% Syntax:
+%   NWBEXPORT(nwb, filename) Writes the nwb object to a file at filename.
+%
+% Input Arguments:
+%   - nwb (NwbFile) - Nwb file object
+%   - filename (string) - Filepath pointing to an NWB file.
+%
+% Usage:
+%  Example 1 - Export an NWB file::
+%
+%    % Create an NWB object with some properties:
+%    nwb = NwbFile;
+%    nwb.session_start_time = datetime('now');
+%    nwb.identifier = 'EMPTY';
+%    nwb.session_description = 'empty test file';
+%
+%    % Write the nwb object to a file:
+%    nwbExport(nwb, 'empty.nwb');
+%
+%  Example 2 - Export an NWB file using an older schema version::
+%
+%    % Generate classes for an older version of NWB schemas:
+%    generateCore('2.5.0')
+%
+%    % Create an NWB object with some properties:
+%    nwb = NwbFile;
+%    nwb.session_start_time = datetime('now');
+%    nwb.identifier = 'EMPTY';
+%    nwb.session_description = 'empty test file';
+%
+%    % Write the nwb object to a file:
+%    nwbExport(nwb, 'empty.nwb');
+%
+% See also:
+%   generateCore, generateExtension, NwbFile, nwbRead
 
     arguments
         nwbFileObjects (1,:) NwbFile {mustBeNonempty}

diff --git a/nwbRead.m b/nwbRead.m
@@ -1,21 +1,53 @@
 function nwb = nwbRead(filename, flags, options)
-    %NWBREAD Reads an NWB file.
-    %  nwb = NWBREAD(filename) Reads the nwb file at filename and returns an
-    %  NWBFile object representing its contents.
-    %  nwb = nwbRead(filename, 'ignorecache') Reads the nwb file without generating classes
-    %  off of the cached schema if one exists.
-    %
-    %  nwb = NWBREAD(filename, options)
-    %
-    %  Requires that core and extension NWB types have been generated
-    %  and reside in a 'types' package on the matlab path.
-    %
-    %  Example:
-    %    nwb = nwbRead('data.nwb');
-    %    nwb = nwbRead('data.nwb', 'ignorecache');
-    %    nwb = nwbRead('data.nwb', 'savedir', '.');
-    %
-    %  See also GENERATECORE, GENERATEEXTENSION, NWBFILE, NWBEXPORT
+% NWBREAD - Read an NWB file.
+%
+% Syntax:
+%  nwb = NWBREAD(filename) Reads the nwb file at filename and returns an
+%  NWBFile object representing its contents.
+%
+%  nwb = NWBREAD(filename, flags) Reads the nwb file using optional 
+%  flags controlling the mode for how to read the file. See input
+%  arguments for a list of available flags.
+%
+%  nwb = NWBREAD(filename, Name, Value) Reads the nwb file using optional 
+%  name-value pairs controlling options for how to read the file.
+%
+% Input Arguments:
+%  - filename (string) - 
+%    Filepath pointing to an NWB file.
+% 
+%  - flags (string) -
+%    Flag for setting the mode for the NWBREAD operation. Available options are:
+%    'ignorecache'. If the 'ignorecache' flag is used, classes for NWB data types
+%    are not re-generated based on the embedded schemas in the file.
+% 
+%  - options (name-value pairs) -
+%    Optional name-value pairs. Available options:
+%  
+%    - savedir (string) -
+%      A folder to save generated classes for NWB types.
+% 
+% Output Arguments:
+%  - nwb (NwbFile) - Nwb file object
+%
+% Usage:
+%  Example 1 - Read an NWB file::
+%
+%    nwb = nwbRead('data.nwb');
+%
+%  Example 2 - Read an NWB file without re-generating classes for NWB types::
+%
+%    nwb = nwbRead('data.nwb', 'ignorecache');
+%
+%  Note: This is a good option to use if you are reading several files
+%  which are created of the same version of the NWB schemas.
+%
+%  Example 3 - Read an NWB file and generate classes for NWB types in the current working directory::
+%
+%    nwb = nwbRead('data.nwb', 'savedir', '.');
+%
+% See also:
+%   generateCore, generateExtension, NwbFile, nwbExport
 
     arguments
         filename (1,1) string {matnwb.common.mustBeNwbFile}