[Bf-blender-cvs] [cd8350764b8] blender-v3.0-release: Docs: improve comments & doc-strings for the tool-system

[Campbell Barton]

Commit: cd8350764b881fbf75b1a0d0ee0f46cd798d17ae
Author: Campbell Barton
Date:   Tue Nov 9 00:14:45 2021 +1100
Branches: blender-v3.0-release
https://developer.blender.org/rBcd8350764b881fbf75b1a0d0ee0f46cd798d17ae

Docs: improve comments & doc-strings for the tool-system

===================================================================

M	release/scripts/startup/bl_ui/space_toolsystem_common.py
M	release/scripts/startup/bl_ui/space_toolsystem_toolbar.py

===================================================================

diff --git a/release/scripts/startup/bl_ui/space_toolsystem_common.py b/release/scripts/startup/bl_ui/space_toolsystem_common.py
index 4305476cb0f..9d41a0fa02f 100644
--- a/release/scripts/startup/bl_ui/space_toolsystem_common.py
+++ b/release/scripts/startup/bl_ui/space_toolsystem_common.py
@@ -202,13 +202,41 @@ class ToolSelectPanelHelper:
     - keymap_prefix:
       The text prefix for each key-map for this spaces tools.
     - tools_all():
-      Returns (context_mode, tools) tuple pair for all tools defined.
+      Generator (context_mode, tools) tuple pairs for all tools defined.
     - tools_from_context(context, mode=None):
-      Returns tools available in this context.
+      A generator for all tools available in the current context.
 
-    Each tool is a 'ToolDef' or None for a separator in the toolbar, use ``None``.
+    Tool Sequence Structure
+    =======================
+
+    Sequences of tools as returned by tools_all() and tools_from_context() are comprised of:
+
+    - A `ToolDef` instance (representing a tool that can be activated).
+    - None (a visual separator in the tool list).
+    - A tuple of `ToolDef` or None values
+      (representing a group of tools that can be selected between using a click-drag action).
+      Note that only a single level of nesting is supported (groups cannot contain sub-groups).
+    - A callable which takes a single context argument and returns a tuple of values described above.
+      When the context is None, all potential tools must be returned.
     """
 
+    @classmethod
+    def tools_all(cls):
+        """
+        Return all tools for this toolbar, this must include all available tools ignoring the current context.
+        The value is must be a sequence of (mode, tool_list) pairs, where mode may be object-mode edit-mode etc.
+        The mode may be None for tool-bars that don't make use of sub-modes.
+        """
+        raise Exception("Sub-class %r must implement this method!" % cls)
+
+    @classmethod
+    def tools_from_context(cls, context, mode=None):
+        """
+        Return all tools for the current context,
+        this result is used at run-time and may filter out tools to display.
+        """
+        raise Exception("Sub-class %r must implement this method!" % cls)
+
     @staticmethod
     def _tool_class_from_space_type(space_type):
         return next(
diff --git a/release/scripts/startup/bl_ui/space_toolsystem_toolbar.py b/release/scripts/startup/bl_ui/space_toolsystem_toolbar.py
index 1a448046f7a..c07487079de 100644
--- a/release/scripts/startup/bl_ui/space_toolsystem_toolbar.py
+++ b/release/scripts/startup/bl_ui/space_toolsystem_toolbar.py
@@ -2583,7 +2583,8 @@ class IMAGE_PT_tools_active(ToolSelectPanelHelper, Panel):
     def tools_all(cls):
         yield from cls._tools.items()
 
-    # for reuse
+    # Private tool lists for convenient reuse in `_tools`.
+
     _tools_transform = (
         _defs_image_uv_transform.translate,
         _defs_image_uv_transform.rotate,
@@ -2609,6 +2610,9 @@ class IMAGE_PT_tools_active(ToolSelectPanelHelper, Panel):
         ),
     )
 
+    # Private tools dictionary, store data to implement `tools_all` & `tools_from_context`.
+    # The keys match image spaces modes: 'context.space_data.mode'.
+    # The values represent the tools, see `ToolSelectPanelHelper` for details.
     _tools = {
         None: [
             # for all modes
@@ -2674,6 +2678,8 @@ class NODE_PT_tools_active(ToolSelectPanelHelper, Panel):
     def tools_all(cls):
         yield from cls._tools.items()
 
+    # Private tool lists for convenient reuse in `_tools`.
+
     _tools_select = (
         (
             _defs_node_select.select,
@@ -2692,6 +2698,9 @@ class NODE_PT_tools_active(ToolSelectPanelHelper, Panel):
         ),
     )
 
+    # Private tools dictionary, store data to implement `tools_all` & `tools_from_context`.
+    # The keys is always `None` since nodes don't use use modes to access different tools.
+    # The values represent the tools, see `ToolSelectPanelHelper` for details.
     _tools = {
         None: [
             *_tools_select,
@@ -2730,7 +2739,8 @@ class VIEW3D_PT_tools_active(ToolSelectPanelHelper, Panel):
     def tools_all(cls):
         yield from cls._tools.items()
 
-    # for reuse
+    # Private tool lists for convenient reuse in `_tools`.
+
     _tools_transform = (
         _defs_transform.translate,
         _defs_transform.rotate,
@@ -2786,6 +2796,9 @@ class VIEW3D_PT_tools_active(ToolSelectPanelHelper, Panel):
         _defs_view3d_generic.ruler,
     )
 
+    # Private tools dictionary, store data to implement `tools_all` & `tools_from_context`.
+    # The keys match object-modes from: 'context.mode'.
+    # The values represent the tools, see `ToolSelectPanelHelper` for details.
     _tools = {
         None: [
             # Don't use this! because of paint modes.
@@ -3095,6 +3108,8 @@ class SEQUENCER_PT_tools_active(ToolSelectPanelHelper, Panel):
     def tools_all(cls):
         yield from cls._tools.items()
 
+    # Private tool lists for convenient reuse in `_tools`.
+
     _tools_select = (
         (
             _defs_sequencer_select.select,
@@ -3110,6 +3125,9 @@ class SEQUENCER_PT_tools_active(ToolSelectPanelHelper, Panel):
         ),
     )
 
+    # Private tools dictionary, store data to implement `tools_all` & `tools_from_context`.
+    # The keys match sequence editors view type: 'context.space_data.view_type'.
+    # The values represent the tools, see `ToolSelectPanelHelper` for details.
     _tools = {
         None: [
         ],