Task SSB-42: Added documentation

CAL/CalibrationCommon/lib/datacontainers/holography_dataset.py

@@ -10,6 +10,11 @@ logger = logging.getLogger(__name__)
 
 class HolographyDataset():
     def __init__(self):
+        '''
+        Initialise the member variables with sane defaults.  Simple types are
+        initialised with None, dicts, lists and other fancy things are
+        initialised with an assignment to their respective constructors.
+        '''
         # float, HDS version
         self.version = HOLOGRAPHY_DATA_SET_VERSION
 
@@ -60,6 +65,14 @@ class HolographyDataset():
 
     @staticmethod
     def compare_dicts(dict1, dict2):
+        '''
+        This function compares the contents of two dicts.  It recursively
+        iterates over all keys and embedded dicts.
+        @return: False if a key in dict1 is not a key in dict2 or if values for
+        a key differ in the dicts, True if the contents of both dicts match.
+        @param dict1:  A dict
+        @param dict2:  Another dict
+        '''
         result = True
         for key in dict1.keys():
             if key in dict2.keys():
@@ -77,6 +90,16 @@ class HolographyDataset():
         return result
     
     def __eq__(self, hds=None):
+        '''
+        This comparison operator compares the values of the relevant members of
+        this class instance and the ones in the parameter hds.  This allows to
+        compare a Holography Data Set in memory with one that has been loaded
+        from an HDF5 file.  It is also possible to compare two HDSs that were
+        imported from Holography Measurement Sets.
+        @param hds:  An instance of the HolographyDataset class
+        @return: True if the values of the members that are relevant for HDS
+        are identical, False otherwise.
+        '''
         equality = False
         if hds is not None and isinstance(hds, HolographyDataset) is True:
             equality = True