Add details in docstrings in bids_interface.py (#442)

moabb/datasets/bids_interface.py

@@ -143,7 +143,7 @@ def lock_file(self):
         )
 
     def erase(self):
-        """Erase the cache of the subject."""
+        """Erase the cache of the subject if it exists."""
         log.info("Starting erasing cache of %s...", repr(self))
         path = mne_bids.BIDSPath(
             root=self.root,
@@ -155,7 +155,15 @@ def erase(self):
         log.info("Finished erasing cache of %s.", repr(self))
 
     def load(self, preload=False):
-        """Load the cache of the subject."""
+        """Load the cache of the subject if it exists and returns it as
+        a nested dictionary with the following structure::
+
+            sessions_data = {'session_id':
+                        {'run_id': run}
+                    }
+
+        If the cache is not present, returns None.
+        """
         log.info("Attempting to retrieve cache of %s...", repr(self))
         self.lock_file.mkdir(exist_ok=True)
         if not self.lock_file.fpath.exists():
@@ -180,7 +188,18 @@ def load(self, preload=False):
         return sessions_data
 
     def save(self, sessions_data):
-        """Save the cache of the subject."""
+        """Save the cache of the subject.
+        The data to be saved should be a nested dictionary
+        with the following structure::
+
+            sessions_data = {'session_id':
+                        {'run_id': run}
+                    }
+
+        If a ``run`` is None, it will be skipped.
+
+        The type of the ``run`` object can vary (see the subclases).
+        """
         log.info("Starting caching %s", {repr(self)})
         mne_bids.BIDSPath(root=self.root).mkdir(exist_ok=True)
         mne_bids.make_dataset_description(
@@ -261,7 +280,10 @@ def _datatype(self):
 
 
 class BIDSInterfaceRawEDF(BIDSInterfaceBase):
-    """BIDS Interface for Raw EDF files. Selected .edf type only."""
+    """BIDS Interface for Raw EDF files. Selected .edf type only.
+
+    In this case, the ``run`` object (see the ``save()`` method)
+    is expected to be an ``mne.io.BaseRaw`` instance."""
 
     @property
     def _extension(self):
@@ -330,6 +352,10 @@ class BIDSInterfaceEpochs(BIDSInterfaceBase):
     """This interface is used to cache mne-epochs to disk.
 
     Pseudo-BIDS format is used to store the data.
+
+
+    In this case, the ``run`` object (see the ``save()`` method)
+    is expected to be an ``mne.Epochs`` instance.
     """
 
     @property
@@ -358,6 +384,10 @@ class BIDSInterfaceNumpyArray(BIDSInterfaceBase):
     """This interface is used to cache numpy arrays to disk.
 
     MOABB Pseudo-BIDS format is used to store the data.
+
+    In this case, the ``run`` object (see the ``save()`` method)
+    is expected to be an ``OrderedDict`` with keys ``"X"`` and
+    ``"events"``. Both values are expected to be ``numpy.ndarray``.
     """
 
     @property