dsmsuite · ernstaii · Jun 12, 2024
diff --git a/DsmSuite.DsmViewer.Application/Actions/Management/ActionManager.cs b/DsmSuite.DsmViewer.Application/Actions/Management/ActionManager.cs
@@ -7,6 +7,10 @@
 
 namespace DsmSuite.DsmViewer.Application.Actions.Management
 {
+    /// <summary>
+    /// Manages user actions.
+    /// This include executing them, undo/redo and keeping a list of all executed actions.
+    /// </summary>
     public class ActionManager : IActionManager
     {
         private readonly Stack<IAction> _undoActionStack;

diff --git a/DsmSuite.DsmViewer.Application/Actions/Management/ActionStore.cs b/DsmSuite.DsmViewer.Application/Actions/Management/ActionStore.cs
@@ -8,10 +8,21 @@
 
 namespace DsmSuite.DsmViewer.Application.Actions.Management
 {
+    /// <summary>
+    /// Stores/restores user actions to/from the model.
+    /// </summary>
+    /// <remarks>
+    /// The ActionType enum tags are used as the action string for the model.
+    /// </remarks>
     public class ActionStore
     {
         private readonly IDsmModel _model;
         private readonly IActionManager _actionManager;
+        // Translate ActionType's to the implementing classes.
+        // The ActionType enum tags are used as the action string for the model.
+        // TODO Isn't a string->Type dictionary more suitable?
+        // TODO Make certain (compile/runtime) all actions are indeed in the table (cut/copy/paste currently aren't)
+        // otherwise we can't load model that we saved.
         private readonly Dictionary<ActionType, Type> _types;
 
         public ActionStore(IDsmModel model, IActionManager actionManager)
@@ -23,6 +34,11 @@ public ActionStore(IDsmModel model, IActionManager actionManager)
             RegisterActionTypes();
         }
 
+        /// <summary>
+        /// Loads all actions from the model into the ActionManager.
+        /// Unrecognized actions are silently ignored.
+        /// If any action cannot be loaded correctly, the ActionManager is cleared.
+        /// </summary>
         public void LoadFromModel()
         {
             foreach (IDsmAction action in _model.GetActions())
@@ -50,6 +66,9 @@ public void LoadFromModel()
             }
         }
 
+        /// <summary>
+        /// Saves all actions in the ActionManager to the model.
+        /// </summary>
         public void SaveToModel()
         {
             if (_actionManager.Validate())
@@ -63,6 +82,7 @@ public void SaveToModel()
 
         private void RegisterActionTypes()
         {
+            //TODO cut/copy/paste actions not present
             _types[ElementChangeNameAction.RegisteredType] = typeof(ElementChangeNameAction);
             _types[ElementChangeTypeAction.RegisteredType] = typeof(ElementChangeTypeAction);
             _types[ElementChangeParentAction.RegisteredType] = typeof(ElementChangeParentAction);

diff --git a/DsmSuite.DsmViewer.Application/ApplicationClasses.cd b/DsmSuite.DsmViewer.Application/ApplicationClasses.cd
@@ -0,0 +1,126 @@
+<?xml version="1.0" encoding="utf-8"?>
+<ClassDiagram MajorVersion="1" MinorVersion="1">
+  <Comment CommentText="manages user actions">
+    <Position X="1.8" Y="2.025" Height="0.325" Width="1.45" />
+  </Comment>
+  <Comment CommentText="Saves/restores user actions to/from the model">
+    <Position X="5.683" Y="3.225" Height="0.5" Width="1.7" />
+  </Comment>
+  <Class Name="DsmSuite.DsmViewer.Application.Core.DsmApplication" Collapsed="true">
+    <Position X="5.5" Y="1.5" Width="1.5" />
+    <AssociationLine Name="_dsmModel" Type="DsmSuite.DsmViewer.Model.Interfaces.IDsmModel" FixedFromPoint="true" FixedToPoint="true">
+      <Path>
+        <Point X="6.656" Y="2.062" />
+        <Point X="6.656" Y="2.26" />
+        <Point X="8.875" Y="2.26" />
+        <Point X="8.875" Y="2.5" />
+      </Path>
+      <MemberNameLabel ManuallyPlaced="true">
+        <Position X="0.693" Y="0.318" />
+      </MemberNameLabel>
+    </AssociationLine>
+    <AssociationLine Name="_actionManager" Type="DsmSuite.DsmViewer.Application.Actions.Management.ActionManager">
+      <MemberNameLabel ManuallyPlaced="true">
+        <Position X="-1.357" Y="0.793" />
+      </MemberNameLabel>
+    </AssociationLine>
+    <AssociationLine Name="_metrics" Type="DsmSuite.DsmViewer.Application.Metrics.DsmMetrics" FixedFromPoint="true" FixedToPoint="true">
+      <Path>
+        <Point X="6.75" Y="1.5" />
+        <Point X="6.75" Y="0.75" />
+        <Point X="8.5" Y="0.75" />
+      </Path>
+    </AssociationLine>
+    <TypeIdentifier>
+      <HashCode>ApE2RAoAJoyABACDABIbREEhoAhopYCERlAgBIUAQIA=</HashCode>
+      <FileName>Core\DsmApplication.cs</FileName>
+    </TypeIdentifier>
+    <ShowAsAssociation>
+      <Field Name="_actionManager" />
+      <Field Name="_actionStore" />
+      <Field Name="_dsmModel" />
+      <Field Name="_metrics" />
+      <Field Name="_queries" />
+    </ShowAsAssociation>
+    <Lollipop Position="0.2" />
+  </Class>
+  <Class Name="DsmSuite.DsmViewer.Application.Actions.Management.ActionManager" Collapsed="true">
+    <Position X="0.75" Y="2.5" Width="1.5" />
+    <AssociationLine Name="_redoActionStack" Type="DsmSuite.DsmViewer.Application.Interfaces.IAction">
+      <MemberNameLabel ManuallyPlaced="true" ManuallySized="true">
+        <Position X="0.143" Y="0.177" Height="0.182" Width="1.328" />
+      </MemberNameLabel>
+    </AssociationLine>
+    <AssociationLine Name="_undoActionStack" Type="DsmSuite.DsmViewer.Application.Interfaces.IAction">
+      <MemberNameLabel ManuallyPlaced="true" ManuallySized="true">
+        <Position X="-1.44" Y="0.235" Height="0.182" Width="1.298" />
+      </MemberNameLabel>
+    </AssociationLine>
+    <TypeIdentifier>
+      <HashCode>AAIQAAQABACABASAAIAAEAIBAAAAAAAAECACAAFAAAA=</HashCode>
+      <FileName>Actions\Management\ActionManager.cs</FileName>
+    </TypeIdentifier>
+    <ShowAsCollectionAssociation>
+      <Field Name="_redoActionStack" />
+      <Field Name="_undoActionStack" />
+    </ShowAsCollectionAssociation>
+    <Lollipop Orientation="Right" Position="0.2" Collapsed="true" />
+  </Class>
+  <Class Name="DsmSuite.DsmViewer.Application.Actions.Management.ActionStore" Collapsed="true">
+    <Position X="5.5" Y="2.5" Width="1.5" />
+    <AssociationLine Name="_model" Type="DsmSuite.DsmViewer.Model.Interfaces.IDsmModel">
+      <MemberNameLabel ManuallyPlaced="true">
+        <Position X="0.552" Y="-0.257" />
+      </MemberNameLabel>
+    </AssociationLine>
+    <TypeIdentifier>
+      <HashCode>AAAAAAAAAAAAAAQAAgAABAAAEAAAAAAAAAAAAEAAQAA=</HashCode>
+      <FileName>Actions\Management\ActionStore.cs</FileName>
+    </TypeIdentifier>
+    <ShowAsAssociation>
+      <Field Name="_model" />
+      <Field Name="_actionManager" />
+    </ShowAsAssociation>
+  </Class>
+  <Class Name="DsmSuite.DsmViewer.Application.Metrics.DsmMetrics" Collapsed="true">
+    <Position X="8.5" Y="0.5" Width="1.5" />
+    <TypeIdentifier>
+      <HashCode>AAAAAAIAAAAAAAAACAAAAAAAAAAAAAAAAAAAAAAAAAA=</HashCode>
+      <FileName>Metrics\DsmMetrics.cs</FileName>
+    </TypeIdentifier>
+  </Class>
+  <Class Name="DsmSuite.DsmViewer.Application.Queries.DsmQueries" Collapsed="true">
+    <Position X="8.5" Y="1.5" Width="1.5" />
+    <AssociationLine Name="_model" Type="DsmSuite.DsmViewer.Model.Interfaces.IDsmModel">
+      <MemberNameLabel ManuallyPlaced="true">
+        <Position X="-0.84" Y="0.135" />
+      </MemberNameLabel>
+    </AssociationLine>
+    <TypeIdentifier>
+      <HashCode>AAEAAAAAAAAAAAACAgACBAAAgABgAQCAAAAAAAAAAIA=</HashCode>
+      <FileName>Queries\DsmQueries.cs</FileName>
+    </TypeIdentifier>
+    <ShowAsAssociation>
+      <Field Name="_model" />
+    </ShowAsAssociation>
+  </Class>
+  <Interface Name="DsmSuite.DsmViewer.Model.Interfaces.IDsmModel" Collapsed="true">
+    <Position X="8.5" Y="2.5" Width="1.5" />
+    <TypeIdentifier />
+  </Interface>
+  <Interface Name="DsmSuite.DsmViewer.Application.Actions.Management.IActionManager" Collapsed="true">
+    <Position X="2.5" Y="2.5" Width="1.5" />
+    <TypeIdentifier>
+      <HashCode>AAIAAAAAAACAAAQAAIAAAAAAAAAAAAAAACAAAABAAAA=</HashCode>
+      <FileName>Actions\Management\IActionManager.cs</FileName>
+    </TypeIdentifier>
+  </Interface>
+  <Interface Name="DsmSuite.DsmViewer.Application.Interfaces.IAction" Collapsed="true">
+    <Position X="0.75" Y="3.75" Width="1.5" />
+    <TypeIdentifier>
+      <HashCode>AAAAAAAAAAAgBEAAAAgAAAAACAAAABAAAQAAAAAAAAA=</HashCode>
+      <FileName>Interfaces\IAction.cs</FileName>
+    </TypeIdentifier>
+  </Interface>
+  <Font Name="Segoe UI" Size="9" />
+</ClassDiagram>
diff --git a/DsmSuite.DsmViewer.Application/DsmSuite.DsmViewer.Application.csproj b/DsmSuite.DsmViewer.Application/DsmSuite.DsmViewer.Application.csproj
@@ -68,7 +68,9 @@
     <Compile Include="Properties\AssemblyInfo.cs" />
     <Compile Include="Queries\DsmQueries.cs" />
   </ItemGroup>
-  <ItemGroup />
+  <ItemGroup>
+    <None Include="ApplicationClasses.cd" />
+  </ItemGroup>
   <ItemGroup>
     <ProjectReference Include="..\DsmSuite.Analyzer.Model\DsmSuite.Analyzer.Model.csproj">
       <Project>{7106d2f0-804e-4f73-950c-266ffc096a87}</Project>

diff --git a/DsmSuite.DsmViewer.Application/Interfaces/ActionType.cs b/DsmSuite.DsmViewer.Application/Interfaces/ActionType.cs
@@ -1,5 +1,9 @@
 namespace DsmSuite.DsmViewer.Application.Interfaces
 {
+    /// <summary>
+    /// The enumeration of all available user actions (i.e. <c>IAction</c> implementors).
+    /// Every enumeration tag should be equal to the name of its implementing class.
+    /// </summary>
     public enum ActionType
     {
         ElementChangeName,

diff --git a/DsmSuite.DsmViewer.Application/Queries/DsmQueries.cs b/DsmSuite.DsmViewer.Application/Queries/DsmQueries.cs
@@ -4,6 +4,12 @@
 
 namespace DsmSuite.DsmViewer.Application.Queries
 {
+    /// <summary>
+    /// Contains some but not all queries the application executes on the model
+    /// </summary>
+    /// TODO Can this class be made more useful?
+    /// DsmApplicaton does some queries as well and dispatches others here. Can we make this class more useful
+    /// by forwarding once and dispatching here?
     public class DsmQueries
     {
         private readonly IDsmModel _model;

diff --git a/DsmSuite.DsmViewer.Model/Core/DsmActionModel.cs b/DsmSuite.DsmViewer.Model/Core/DsmActionModel.cs
@@ -4,6 +4,9 @@
 
 namespace DsmSuite.DsmViewer.Model.Core
 {
+    /// <summary>
+     /// Manages the actions of a model. Only used by DsmModel, which forwards calls here.
+     /// </summary>
     public class DsmActionModel : IDsmActionModelFileCallback
     {
         private readonly List<IDsmAction> _actions;

diff --git a/DsmSuite.DsmViewer.Model/Core/DsmElementModel.cs b/DsmSuite.DsmViewer.Model/Core/DsmElementModel.cs
@@ -6,6 +6,9 @@
 
 namespace DsmSuite.DsmViewer.Model.Core
 {
+    /// <summary>
+    /// Manages the elements of a model. Only used by DsmModel, which forwards calls here.
+    /// </summary>
     public class DsmElementModel : IDsmElementModelFileCallback
     {
         private readonly Dictionary<int /*id*/, DsmElement> _elementsById;

diff --git a/DsmSuite.DsmViewer.Model/Core/DsmRelationModel.cs b/DsmSuite.DsmViewer.Model/Core/DsmRelationModel.cs
@@ -6,6 +6,9 @@
 
 namespace DsmSuite.DsmViewer.Model.Core
 {
+    /// <summary>
+    /// Manages the relations of a model. Only used by DsmModel, which forwards calls here.
+    /// </summary>
     public class DsmRelationModel : IDsmRelationModelFileCallback
     {
         private readonly Dictionary<int /*relationId*/, DsmRelation> _relationsById;

diff --git a/DsmSuite.DsmViewer.Model/DsmSuite.DsmViewer.Model.csproj b/DsmSuite.DsmViewer.Model/DsmSuite.DsmViewer.Model.csproj
@@ -61,7 +61,9 @@
       <Name>DsmSuite.Common.Util</Name>
     </ProjectReference>
   </ItemGroup>
-  <ItemGroup />
+  <ItemGroup>
+    <None Include="ModelClasses.cd" />
+  </ItemGroup>
   <Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />
   <!-- To modify your build process, add your task inside one of the targets below and uncomment it. 
        Other similar extension points exist, see Microsoft.Common.targets.

diff --git a/DsmSuite.DsmViewer.Model/Interfaces/IDsmModel.cs b/DsmSuite.DsmViewer.Model/Interfaces/IDsmModel.cs
@@ -5,6 +5,16 @@
 
 namespace DsmSuite.DsmViewer.Model.Interfaces
 {
+    /// <summary>
+    /// Represents a domain structure matrix. A Dsm model consists of a hierarchy of elements
+    /// <see cref="IDsmElement"/>, relations <see cref="IDsmRelation"/> between elements and a
+    /// sequence of actions <see cref="IDsmAction"/> that were executed on the model.
+    /// </summary>
+    /// <remarks>
+    /// Models can be saved and loaded. Element and relations can have types (strings) assigned
+    /// to them. Actions are strings as well. The model is agnostic about the meaning of
+    /// actions and element/relation types.
+    /// </remarks>
     public interface IDsmModel
     {
         // Cleanup