Document API properly

concert_workspacecreator.py

@@ -4,9 +4,12 @@ import PyTango
 
 
 class Workspace(object):
+
+    """A workspace."""
+
     def __init__(self, device, workspace_id):
         self._device = device
-        self._workspace_id = workspace_id
+        self._id = workspace_id
         self._path = device.GetWorkspacePath(workspace_id)
         logging.getLogger().info("Create {}".format(self))
 
@@ -17,26 +20,43 @@ class Workspace(object):
         self.close()
 
     def __repr__(self):
-        return '<Workspace:id={} path={}>'.format(self._workspace_id, self._path)
+        return '<Workspace:id={} path={}>'.format(self.id, self._path)
+
+    @property
+    def id(self):
+        """Unique id of this workspace."""
+        return self._id
 
     @property
     def path(self):
+        """Path associated with the workspace"""
         return self._path
 
     def close(self):
-        self._device.CloseWorkspace(self._workspace_id)
+        """Close this workspace."""
+        self._device.CloseWorkspace(self.id)
         logging.getLogger().info("Closed {}".format(self))
 
 
 class WorkspaceCreator(object):
+
+    """Workspace creation facility."""
+
     def __init__(self, device_name):
+        """
+        Args:
+            device_name (str): TANGO device name
+        """
         try:
             self._device = PyTango.DeviceProxy(device_name)
         except PyTango.DevFailed as e:
             raise IOError("PyTango: {}".format(e[0].desc))
 
-        self._last_workspace = None
-
     def create(self):
+        """Create a new workspace.
+
+        Returns:
+            Workspace: A new workspace object
+        """
         workspace_id = self._device.CreateWorkspace()
         return Workspace(self._device, workspace_id)