Rename messages + add more documentation

ipywidgets/widgets/widget.py

@@ -333,7 +333,10 @@ def handle_control_comm_msg(cls, msg):
         if cls._control_comm is None:
             raise RuntimeError('Control comm has not been properly opened')
 
-        if msg['content']['data']['type'] == 'models-request':
+        data = msg['content']['data']
+        method = data['method']
+
+        if method == 'request_states':
             # Send back the full widgets state
             cls.get_manager_state()
             widgets = Widget.widgets.values()
@@ -347,9 +350,14 @@ def handle_control_comm_msg(cls, msg):
                     'state': widget.get_state(drop_defaults=drop_defaults),
                 }
             full_state, buffer_paths, buffers = _remove_buffers(full_state)
-            cls._control_comm.send([full_state, buffer_paths], buffers=buffers)
+            cls._control_comm.send(dict(
+                method='states',
+                states=full_state,
+                buffer_paths=buffer_paths
+            ), buffers=buffers)
+
         else:
-            raise RuntimeError('Control comm msg "{}" not implemented'.format(msg['content']['data']['type']))
+            self.log.error('Unknown front-end to back-end widget control msg with method "%s"' % method)
 
     @staticmethod
     def handle_comm_opened(comm, msg):

packages/schema/messages.md

@@ -348,6 +348,34 @@ This is implemented in ipywidgets 7.7.
 
 ### The `jupyter.widget.control` comm target
 
-A kernel-side Jupyter widgets library registers a `jupyter.widget.control` comm target that is used for fetching all widgets states through a "one shot" comm message (one for all widget instances).
+A kernel-side Jupyter widgets library registers a `jupyter.widget.control` comm target that is used for fetching all widgets states through a "one shot" comm message (one for all widget instances). Unlike the `jupyter.widget` comm target, the created comm is global to all widgets,
 
-The kernel-side widgets library must answer to the `{"type": "models-request"}` message with a comm message containing the full state of all widget instances.
+#### State requests: `request_states`
+
+When a frontend wants to request the full state of a all widgets, the frontend sends a `request_states` message:
+
+```
+{
+  'comm_id' : 'u-u-i-d',
+  'data' : {
+    'method': 'request_states'
+  }
+}
+```
+
+The kernel side of the widget should immediately send an `states` message with all widgets states:
+
+```
+{
+  'comm_id' : 'u-u-i-d',
+  'data' : {
+    'method': 'states',
+    'states': {
+      <widget1 u-u-i-d>: <widget1 state>,
+      <widget2 u-u-i-d>: <widget2 state>,
+      [...]
+    },
+    'buffer_paths': [ <list with paths corresponding to the binary buffers> ]
+  }
+}
+```