add gui class docstrings

Author: ptooley

pypop/notebook_interface/fileselector.py

@@ -20,11 +20,22 @@
 
 
 class ValidatingChooser(VBox):
+    """IPyWidgets GUI Element for file selection with validation
+    """
 
     _container_layout = Layout(margin="1em 0em 1em 0em")
     _msgbox_layout = Layout()
 
     def __init__(self, starting_file=None, starting_path=None, **kwargs):
+        """\
+        Parameters
+        ----------
+        starting_file: str or None
+            If not None, file that is initially selected.
+        starting_path: str or None
+            Starting directory for filechooser. If none, defaults to value of
+            `os.getcwd()`
+        """
 
         if starting_file is None:
             starting_file = ""
@@ -61,6 +72,9 @@ def selected(self):
 
 
 class FileSelector(VBox):
+    """IPyWidgets GUI Element for selecting arbitrary numbers of files with callback
+    support
+    """
 
     _button_container_layout = Layout(
         display="flex",
@@ -77,13 +91,29 @@ class FileSelector(VBox):
 
     def __init__(
         self,
-        base_dir=".",
+        base_dir=None,
         starting_files=None,
         calculation_callback=None,
         analysis_state=None,
         **kwargs
     ):
-        self._base_dir = base_dir
+        """\
+        Parameters
+        ----------
+
+        base_dir: str or None
+            Starting directory for filechooser. If None defaults to `os.getcwd()`.
+        starting_files: list of str or None
+            List of files to be initially selected.
+        calculation_callback: callable
+            Function to be executed when calculation button is pressed. Should have the
+            standard IPyWidgets Button callback signature `f(WidgetInstance)`
+        analysis_state: AnalysisState
+            Saved analysis state to be passed in (overrides default options
+            with those saved)
+        """
+
+        self._base_dir = base_dir if base_dir else getcwd()
         self._files = (
             [None]
             if starting_files is None

pypop/notebook_interface/wizard.py

@@ -15,6 +15,13 @@
 from pypop.utils.exceptions import ExtraePRVNoOnOffEventsError
 
 class TypeAsserter:
+    """Parent class for type asserter objects
+
+    Asserter classes provide a callable which can be used to assert the validity of an
+    object.
+
+    Subclasses should implement a check_type function returning true/false as needed.
+    """
 
     _expected = None
 
@@ -26,23 +33,44 @@ def __call__(self, testobj):
         return True
 
     def check_type(self, testobj):
+        """Return true if object is valid
+
+        Parameters
+        ----------
+        testobj: object
+            Object to be validated.
+        """
         raise NotImplementedError()
 
 
 class SimpleAsserter(TypeAsserter):
+    """Assert that an object is of a given type
+
+    Provides a callable object which asserts the provided object is of the required type.
+    """
+
+    def __init__(self, assert_class):
+        """Define class to be validated
+
+        Parameters
+        ----------
+        assert_class: class
+            Reference class to be compared to.
+        """
+        self._assert_cls = assert_class
+        self._exepceted = assert_class.__name__
+
+
     def check_type(self, testobj):
         if isinstance(testobj, self._assert_cls):
             return True
 
-    @staticmethod
-    def create(assert_cls):
-        asserter = SimpleAsserter()
-        asserter._assert_cls = assert_cls
-        asserter._expected = assert_cls.__name__
-        return asserter
-
 
 class ListofStrAsserter(TypeAsserter):
+    """Assert that an object is a list of strings
+
+    Provides a callable object which asserts a provided object is a list of strings.
+    """
     _expected = "list of str"
 
     def check_type(self, testobj):
@@ -51,10 +79,14 @@ def check_type(self, testobj):
 
 
 class AnalysisState:
+    """Object containing analysis settings
+
+    This is an internal class and not intended for direct use.
+    """
 
     _required_params = {
         "trace_files": ListofStrAsserter(),
-        "metrics_object": SimpleAsserter.create(pm.MetricSet),
+        "metrics_object": SimpleAsserter(pm.MetricSet),
     }
 
     _optional_params = {}
@@ -109,7 +141,24 @@ def __setitem__(self, key, value):
 
 
 class MetricsWizard(Tab):
+    """IPyWidgets GUI Element providing an analysis Wizard.
+    """
     def __init__(self, metric_calc="auto", base_dir=".", starting_files=None, **kwargs):
+        """
+
+        Parameters
+        ----------
+
+        metric_calc: class MetricSet or 'auto'
+            Provide a specific metric calculator class. If 'auto' is passed then try to
+            choose a suitable default.
+
+        base_dir: str
+            Starting directory for the filechooser. Defaults to result of `os.getcwd()`.
+
+        starting_files: list of str
+            List of files that should be preselected in the file chooser.
+        """
 
         self._metrics_display = None
         self._scaling_plot = None