From e90db5bca43a2d97b086cdfc5fa0215661b1365d Mon Sep 17 00:00:00 2001
From: "Dipl.-Ing. Jonas Stienen" <jst@akustik.rwth-aachen.de>
Date: Wed, 16 May 2018 08:52:13 +0200
Subject: [PATCH] More documentation for DAFF class

---
 .../openDAFF/OpenDAFFv1.7/DAFF.m              | 117 ++++++++++++------
 1 file changed, 82 insertions(+), 35 deletions(-)

diff --git a/applications/VirtualAcoustics/openDAFF/OpenDAFFv1.7/DAFF.m b/applications/VirtualAcoustics/openDAFF/OpenDAFFv1.7/DAFF.m
index c414137b..a95aef5f 100644
--- a/applications/VirtualAcoustics/openDAFF/OpenDAFFv1.7/DAFF.m
+++ b/applications/VirtualAcoustics/openDAFF/OpenDAFFv1.7/DAFF.m
@@ -1,77 +1,124 @@
 classdef DAFF < handle
+    
+    % DAFF is a direction audio file format for virtual acoustics
+    % A daff file instance can be used to load a file in DAFF format and 
+    % receiver metadata, proerties and directional audio content.
+    %
+    % The most important functions are
+    %
+    %   load                        Open a DAFF file
+    %   close                       Closes a DAFF file
+    %   nearest_neighbour_record    Receive content for a certain direction in spherical coordinates
+    %   metadata                    Get DAFF metadata as struct
+    %   properties                  Get DAFF properties as struct
+    %
+    
    properties (Access = protected)
-      daffhandle
-      view = 'object'
+       
+      daffhandle % The internal DAFF file handle
+      view = 'object' % The DAFF viewpoint (user/object or developer/data)
+      
    end
+   
    methods
+       
         function obj = DAFF( filepath )
-            %% Create DAFF class and loads content from file
-            % filepath Path to DAFF file
+            % Creates a DAFF instance and loads content from file
+            %   filepath    Path to DAFF file
             if( nargin > 0 )
                 obj.open( filepath )
             end
         end
+        
         function open( obj, filepath )
-			%% Opens a DAFF file
+			% Opens a DAFF file
              obj.daffhandle = DAFFv17( 'open', filepath );
         end
+        
         function close( obj )
-			%% Closes the DAFF file
+			% Closes the DAFF file
 			DAFFv17( 'close', obj.daffhandle )
         end
+        
         function set_data_view( obj )
-			%% Switches to data view (alpha, beta)
+			% Switches to data view (alpha, beta)
              obj.view = 'data';
         end
         function set_object_view( obj )
-			%% Switches to object / user view (elevation, azimuth) [default]
+			% Switches to object / user view (elevation, azimuth) [default]
              obj.view = 'object';
         end        
-        function metadata = get_metadata(obj)
-            %% Returns the metadata of an opened DAFF file
-            metadata = DAFFv17('getMetadata', obj.daffhandle);
+        function metadata = metadata(obj)
+            % Returns the metadata of an opened DAFF file
+            metadata = DAFFv17( 'getMetadata', obj.daffhandle );
         end
-        function metadata = get_record_metadata( obj, index )
-            %% Returns the record metadata of an opened DAFF file
-            metadata = DAFFv17('getRecordMetadata', obj.daffhandle, index);
+        function metadata = record_metadata( obj, index )
+            % Returns the record metadata of an opened DAFF file
+            metadata = DAFFv17( 'getRecordMetadata', obj.daffhandle, index );
         end
-        function props = get_properties( obj )
-            %% Returns the properties of an opened DAFF file
+        function props = properties( obj )
+            % Returns the properties of an opened DAFF file
             props = DAFFv17( 'getProperties', obj.daffhandle );
         end
-        function coords = get_record_coords( obj, index )
-            %% Returns the coordinates of a grid point
+        function coords = record_coords( obj, index )
+            % Returns the coordinates of a grid point
             coords = DAFFv17( 'getRecordCoords', obj.daffhandle, obj.view, index );
         end
-        function idx = get_nearest_neighbour_index( obj, azi_deg, ele_deg )
-            %% Returns the data at the nearest neighbour grid point to the given direction
+        function idx = nearest_neighbour_index( obj, azi_deg, ele_deg )
+            % Returns the data at the nearest neighbour grid point to the given direction
+            % Uses spherical coordinates azimuth and elevation in degree.
+            %
+            %   azi_deg     Azimuthal angle in degree
+            %   ele_deg     Elevation angle in degree
+            %
             idx = DAFFv17( 'getNearestNeighbourIndex', obj.daffhandle, obj.view, azi_deg, ele_deg );
         end
-        function data = get_nearest_neighbour_record( obj, azi_deg, ele_deg )
-            %% Returns the data at the nearest neighbour grid point to the given direction
+        function data = nearest_neighbour_record( obj, azi_deg, ele_deg )
+            % Returns the data at the nearest neighbour grid point to the given direction
+            % Uses spherical coordinates azimuth and elevation in degree.
+            %
+            %   azi_deg     Azimuthal angle in degree
+            %   ele_deg     Elevation angle in degree
+            %
             data = DAFFv17( 'getNearestNeighbourRecord', obj.daffhandle, obj.view, azi_deg, ele_deg );
         end
-        function rec = get_record_by_index( obj, idx )
-            %% Returns the data at a grid of the given index
+        function rec = record_by_index( obj, idx )
+            % Returns the data at a grid of the given index
             rec = DAFFv17( 'getRecordByIndex', obj.daffhandle, idx );
         end
-        function data = get_cell_records( obj, azi_deg, ele_deg )
-            %% Returns the data of all four records of the surrounding cell to the given direction
+        function data = cell_records( obj, azi_deg, ele_deg )
+            % Returns the data of all four records of the surrounding cell to the given direction
+            % Uses spherical coordinates azimuth and elevation in degree.
+            %
+            %   azi_deg     Azimuthal angle in degree
+            %   ele_deg     Elevation angle in degree
+            %
             data = DAFFv17('getCellRecords', obj.daffhandle, obj.view, azi_deg, ele_deg );
         end
-        function idx = get_cell( obj, azi_deg, ele_deg )
-            %% Returns the data at the nearest neighbour grid point to the given direction
+        function idx = cell( obj, azi_deg, ele_deg )
+            % Returns the data at the nearest neighbour grid point to the given direction
+            % Uses spherical coordinates azimuth and elevation in degree.
+            %
+            %   azi_deg     Azimuthal angle in degree
+            %   ele_deg     Elevation angle in degree
+            %
             idx = DAFFv17( 'getCell', obj.daffhandle, obj.view, azi_deg, ele_deg );
         end
+        
    end
+   
     methods (Static)
-        function help()
-            %% Prints the help output of OpenDAFF
-            DAFFv17('help')
+        
+        function mex_help()
+            % Prints the help output of OpenDAFF extension (mex)
+            DAFFv17( 'help' )
         end
-        function v = get_version()
-            %% Returns the OpenDAFF version
-            v = DAFFv17('getVersion');
+        
+        function v = mex_version()
+            % Returns the OpenDAFF extension (mex) version
+            v = DAFFv17( 'getVersion' );
         end
-   end
+        
+    end
+   
 end
-- 
GitLab