[Bf-blender-cvs] [d9b9f530909] workspaces: Comments: Try to describe WorkSpaceDataAssignment struct better

[Julian Eisel]

Commit: d9b9f530909e396225598dce56305e87f051f163
Author: Julian Eisel
Date:   Tue Apr 4 13:51:32 2017 +0200
Branches: workspaces
https://developer.blender.org/rBd9b9f530909e396225598dce56305e87f051f163

Comments: Try to describe WorkSpaceDataAssignment struct better

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

M	source/blender/makesdna/dna_workspace_types.h

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

diff --git a/source/blender/makesdna/dna_workspace_types.h b/source/blender/makesdna/dna_workspace_types.h
index 8a47b30d406..914b252a0de 100644
--- a/source/blender/makesdna/dna_workspace_types.h
+++ b/source/blender/makesdna/dna_workspace_types.h
@@ -64,10 +64,22 @@ typedef struct WorkSpace {
  * Generic (and simple/primitive) struct for storing a history of assignments/relations
  * of workspace data to non-workspace data in a listbase inside the workspace.
  *
- * We use it to store:
- * * Active layout of each workspace per hook (= per window) -- Workspace stores an active layout for each hook.
- *
  * Using this we can restore the old state of a workspace if the user switches back to it.
+ *
+ * \example When activating a workspace, it should activate the screen-layout that was active in that
+ *          workspace before *in this window*.
+ *          More concretely:
+ *          * There are two windows, win1 and win2.
+ *          * Both show workspace ws1, but both also had workspace ws2 activated at some point before.
+ *          * Last time ws2 was active in win1, screen-layout sl1 was activated.
+ *          * Last time ws2 was active in win2, screen-layout sl2 was activated.
+ *          * When changing from ws1 to ws2 in win1, screen-layout sl1 should be activated again.
+ *          * When changing from ws1 to ws2 in win2, screen-layout sl2 should be activated again.
+ *          So that means we have to store the active screen-layout in a per workspace, per window
+ *          relation. This struct is used to store an active screen-layout for each window within the
+ *          workspace.
+ *          To find the screen-layout to activate for this window-workspace combination, simply lookup
+ *          the WorkSpaceDataAssignment with the workspace-hook of the window set as parent.
  */
 typedef struct WorkSpaceDataAssignment {
 	struct WorkSpaceDataAssignment *next, *prev;