Re #1786 better comments, longer test runs.

_test/test_utilities_herbert/fast_map_vs_map_performance.m

@@ -1,4 +1,4 @@
-n_keys = 100;
+n_keys = 500;
 base_key = 10+round(rand(1,10*n_keys)*(10*n_keys-1));
 base_key = unique(base_key);
 
@@ -7,7 +7,7 @@
 keysUint = uint32(base_key);
 mm = min_max(keysUint)
 
-n_operations= 10000;
+n_operations= 50000;
 
 
 test_keys = repmat(base_key,1,n_operations);

herbert_core/utilities/classes/@fast_map/fast_map.m

@@ -22,7 +22,16 @@
     properties
         % map optimization for doing fast access limit
         %
-        % The map optimization works by allocating large array with places
+        % The map optimization works by allocating large continuous array
+        % with places for keys as indices. Where keys correspond places in
+        % array, result contains values, and where no keys present, array
+        % contains nan-s. The property below shows how much more elements
+        % the optimization array should contain wrt the number of keys in
+        % the map. E.g. if empty_space_optimization_limit == 5 and there
+        % are 100 keys, optimization array would contain 500 elements.
+        % If max(keys)-min(keys) > number_of_keys*empty_space_optimization_limit,
+        % map optimization gets disabled and correspondence between keys
+        % and values is calculated by binary search.
         empty_space_optimization_limit = 5;
     end
 
@@ -163,6 +172,22 @@
         end
         %
         function val = get_values_for_keys(self,keys,no_validity_checks)
+            % method retrieves values corresponding to array of keys.
+            %
+            % Using this method for array of keys is approximately two
+            % times faster than retrieving array of values invoking get(key)
+            % method.
+            %
+            % Inputs:
+            % self  -- initialized  instance of fast map class
+            % keys  -- array of numerical keys
+            % no_validity_checks
+            %       --  if true, keys assumed to be valid and validity
+            %           check for keys is not performed (~5 times faster)
+            %           Invalid keys will still throw in optimized map but
+            %           error will be less
+            %
+            %
             if nargin<3
                 no_validity_checks = false;
             end