Updating comments

Signed-off-by: Guthrie Adams <guthadam@amazon.com>

Gems/Atom/Tools/AtomToolsFramework/Code/Include/AtomToolsFramework/Application/AtomToolsApplication.h

@@ -111,7 +111,7 @@ namespace AtomToolsFramework
 
         AZStd::unique_ptr<AzQtComponents::StyleManager> m_styleManager;
 
-        //! Local user settings are used to store material browser tree expansion state
+        //! Local user settings are used to store asset browser tree expansion state
         AZ::UserSettingsProvider m_localUserSettings;
 
         //! Are local settings loaded

Gems/Atom/Tools/AtomToolsFramework/Code/Include/AtomToolsFramework/Document/AtomToolsDocument.h

@@ -58,29 +58,36 @@ namespace AtomToolsFramework
         virtual bool OpenSucceeded();
         virtual bool OpenFailed();
 
-        virtual bool ReopenRecordState();
-        virtual bool ReopenRestoreState();
-
         virtual bool SaveSucceeded();
         virtual bool SaveFailed();
 
-        // Unique id of this document
+        //! Record state that needs to be restored after a document is reopened.
+        //! This can be overridden to record additional data.
+        virtual bool ReopenRecordState();
+
+        //! Restore state that was recorded prior to document being reloaded.
+        //! This can be overridden to restore additional data.
+        virtual bool ReopenRestoreState();
+
+        //! The unique id of this document, used for all bus notifications and requests.
         AZ::Uuid m_id = AZ::Uuid::CreateRandom();
 
-        // Absolute path to the material source file
+        //! The absolute path to the document source file.
         AZStd::string m_absolutePath;
 
+        //! The normalized, absolute path where the document will be saved.
         AZStd::string m_savePathNormalized;
 
         AZStd::any m_invalidValue;
         
         AtomToolsFramework::DynamicProperty m_invalidProperty;
 
-        // Set of assets that can trigger a document reload
+        //! This contains absolute paths of other source files that affect this document.
+        //! If any of the source files in this container are modified, the document system will he notified to reload this document.
         AZStd::unordered_set<AZStd::string> m_sourceDependencies;
 
-        // Track if document saved itself last to skip external modification notification
-        bool m_saveTriggeredInternally = false;
+        //! If this flag is true then the next source file change notification for this document will be ignored.
+        bool m_ignoreSourceFileChangeToSelf = false;
 
         // Variables needed for tracking the undo and redo state of this document
 
@@ -101,6 +108,7 @@ namespace AtomToolsFramework
         int m_undoHistoryIndex = {};
         int m_undoHistoryIndexBeforeReopen = {};
 
+        //! Add new undo redo command functions at the current position in the undo history.
         void AddUndoRedoHistory(const UndoRedoFunction& undoCommand, const UndoRedoFunction& redoCommand);
 
         // AzToolsFramework::AssetSystemBus::Handler overrides...

Gems/Atom/Tools/AtomToolsFramework/Code/Source/Document/AtomToolsDocument.cpp

@@ -122,7 +122,7 @@ namespace AtomToolsFramework
 
         if (!IsSavable())
         {
-            AZ_Error("AtomToolsDocument", false, "Material types can only be saved as a child: '%s'.", m_absolutePath.c_str());
+            AZ_Error("AtomToolsDocument", false, "Document type can not be saved: '%s'.", m_absolutePath.c_str());
             return SaveFailed();
         }
 
@@ -146,7 +146,7 @@ namespace AtomToolsFramework
 
         if (!IsSavable())
         {
-            AZ_Error("AtomToolsDocument", false, "Material types can only be saved as a child: '%s'.", m_absolutePath.c_str());
+            AZ_Error("AtomToolsDocument", false, "Document type can not be saved: '%s'.", m_absolutePath.c_str());
             return SaveFailed();
         }
 
@@ -170,7 +170,7 @@ namespace AtomToolsFramework
 
         if (m_absolutePath == m_savePathNormalized || m_sourceDependencies.find(m_savePathNormalized) != m_sourceDependencies.end())
         {
-            AZ_Error("AtomToolsDocument", false, "Document can't be saved over a dependancy: '%s'.", m_savePathNormalized.c_str());
+            AZ_Error("AtomToolsDocument", false, "Document can not be saved over a dependancy: '%s'.", m_savePathNormalized.c_str());
             return SaveFailed();
         }
 
@@ -268,7 +268,7 @@ namespace AtomToolsFramework
 
         m_absolutePath.clear();
         m_sourceDependencies.clear();
-        m_saveTriggeredInternally = {};
+        m_ignoreSourceFileChangeToSelf = {};
         m_undoHistory.clear();
         m_undoHistoryIndex = {};
     }
@@ -289,26 +289,9 @@ namespace AtomToolsFramework
         return false;
     }
 
-    bool AtomToolsDocument::ReopenRecordState()
-    {
-        // Store history and property changes that should be reapplied after reload
-        m_undoHistoryBeforeReopen = m_undoHistory;
-        m_undoHistoryIndexBeforeReopen = m_undoHistoryIndex;
-        return true;
-    }
-
-    bool AtomToolsDocument::ReopenRestoreState()
-    {
-        m_undoHistory = m_undoHistoryBeforeReopen;
-        m_undoHistoryIndex = m_undoHistoryIndexBeforeReopen;
-        m_undoHistoryBeforeReopen = {};
-        m_undoHistoryIndexBeforeReopen = {};
-        return true;
-    }
-
     bool AtomToolsDocument::SaveSucceeded()
     {
-        m_saveTriggeredInternally = true;
+        m_ignoreSourceFileChangeToSelf = true;
 
         AZ_TracePrintf("AtomToolsDocument", "Document saved: '%s'.\n", m_savePathNormalized.c_str());
 
@@ -328,6 +311,22 @@ namespace AtomToolsFramework
         return false;
     }
 
+    bool AtomToolsDocument::ReopenRecordState()
+    {
+        m_undoHistoryBeforeReopen = m_undoHistory;
+        m_undoHistoryIndexBeforeReopen = m_undoHistoryIndex;
+        return true;
+    }
+
+    bool AtomToolsDocument::ReopenRestoreState()
+    {
+        m_undoHistory = m_undoHistoryBeforeReopen;
+        m_undoHistoryIndex = m_undoHistoryIndexBeforeReopen;
+        m_undoHistoryBeforeReopen = {};
+        m_undoHistoryIndexBeforeReopen = {};
+        return true;
+    }
+
     void AtomToolsDocument::AddUndoRedoHistory(const UndoRedoFunction& undoCommand, const UndoRedoFunction& redoCommand)
     {
         // Wipe any state beyond the current history index
@@ -349,13 +348,13 @@ namespace AtomToolsFramework
         if (m_absolutePath == sourcePath)
         {
             // ignore notifications caused by saving the open document
-            if (!m_saveTriggeredInternally)
+            if (!m_ignoreSourceFileChangeToSelf)
             {
                 AZ_TracePrintf("AtomToolsDocument", "Document changed externally: '%s'.\n", m_absolutePath.c_str());
                 AtomToolsFramework::AtomToolsDocumentNotificationBus::Broadcast(
                     &AtomToolsFramework::AtomToolsDocumentNotificationBus::Events::OnDocumentExternallyModified, m_id);
             }
-            m_saveTriggeredInternally = false;
+            m_ignoreSourceFileChangeToSelf = false;
         }
         else if (m_sourceDependencies.find(sourcePath) != m_sourceDependencies.end())
         {

Gems/Atom/Tools/AtomToolsFramework/Code/Source/Document/AtomToolsDocumentSystemComponent.h

@@ -24,7 +24,7 @@ AZ_POP_DISABLE_WARNING
 
 namespace AtomToolsFramework
 {
-    //! AtomToolsDocumentSystemComponent is the central component of the Material Editor Core gem
+    //! AtomToolsDocumentSystemComponent is the central component for managing documents
     class AtomToolsDocumentSystemComponent
         : public AZ::Component
         , private AtomToolsDocumentNotificationBus::Handler

Gems/Atom/Tools/AtomToolsFramework/Code/Source/PreviewRenderer/PreviewRendererCaptureState.h

@@ -14,7 +14,7 @@
 
 namespace AtomToolsFramework
 {
-    //! PreviewRendererCaptureState renders a thumbnail to a pixmap and notifies MaterialOrModelThumbnail once finished
+    //! PreviewRendererCaptureState renders a preview to an image
     class PreviewRendererCaptureState final
         : public PreviewRendererState
         , public AZ::TickBus::Handler
@@ -31,7 +31,7 @@ namespace AtomToolsFramework
         //! AZ::Render::FrameCaptureNotificationBus::Handler overrides...
         void OnCaptureFinished(AZ::Render::FrameCaptureResult result, const AZStd::string& info) override;
 
-        //! This is necessary to suspend capture to allow a frame for Material and Mesh components to assign materials
+        //! This is necessary to suspend capture until preview scene is ready
         int m_ticksToCapture = 1;
     };
 } // namespace AtomToolsFramework

Gems/Atom/Tools/MaterialEditor/Code/Source/Document/MaterialDocument.h

@@ -77,6 +77,7 @@ namespace MaterialEditor
         bool SavePropertiesToSourceData(
             const AZStd::string& exportPath, AZ::RPI::MaterialSourceData& sourceData, PropertyFilterFunction propertyFilter) const;
 
+        // AtomToolsFramework::AtomToolsDocument overrides...
         void Clear() override;
 
         bool ReopenRecordState() override;

Gems/Atom/Tools/MaterialEditor/Code/Source/Viewport/MaterialViewportComponent.cpp

@@ -442,16 +442,16 @@ namespace MaterialEditor
             if (AZ::StringFunc::EndsWith(assetInfo.m_relativePath.c_str(), ".lightingpreset.azasset"))
             {
                 m_lightingPresetAssets[assetInfo.m_assetId] = { assetInfo.m_assetId, assetInfo.m_assetType };
-                AZ::Data::AssetBus::MultiHandler::BusConnect(assetInfo.m_assetId);
                 m_lightingPresetAssets[assetInfo.m_assetId].QueueLoad();
+                AZ::Data::AssetBus::MultiHandler::BusConnect(assetInfo.m_assetId);
                 return;
             }
 
             if (AzFramework::StringFunc::EndsWith(assetInfo.m_relativePath.c_str(), ".modelpreset.azasset"))
             {
                 m_modelPresetAssets[assetInfo.m_assetId] = { assetInfo.m_assetId, assetInfo.m_assetType };
-                AZ::Data::AssetBus::MultiHandler::BusConnect(assetInfo.m_assetId);
                 m_modelPresetAssets[assetInfo.m_assetId].QueueLoad();
+                AZ::Data::AssetBus::MultiHandler::BusConnect(assetInfo.m_assetId);
                 return;
             }
         };

Gems/Atom/Tools/ShaderManagementConsole/Code/Source/Document/ShaderManagementConsoleDocument.h

@@ -49,7 +49,9 @@ namespace ShaderManagementConsole
         const AZ::RPI::ShaderOptionDescriptor& GetShaderOptionDescriptor(size_t index) const override;
 
     private:
+        // AtomToolsFramework::AtomToolsDocument overrides...
         void Clear() override;
+
         bool SaveSourceData();
 
         // Source data for shader variant list
@@ -58,6 +60,6 @@ namespace ShaderManagementConsole
         // Shader asset for the corresponding shader variant list
         AZ::Data::Asset<AZ::RPI::ShaderAsset> m_shaderAsset;
 
-        const AZ::RPI::ShaderOptionDescriptor m_invalidDescriptor;
+        AZ::RPI::ShaderOptionDescriptor m_invalidDescriptor;
     };
 } // namespace ShaderManagementConsole