updated comments

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

Gems/Atom/Tools/AtomToolsFramework/Code/Include/AtomToolsFramework/Util/MaterialPropertyUtil.h

@@ -36,7 +36,7 @@ namespace AtomToolsFramework
     //! Convert and assign material property meta data fields to editor dynamic property configuration 
     void ConvertToPropertyConfig(AtomToolsFramework::DynamicPropertyConfig& propertyConfig, const AZ::RPI::MaterialPropertyDynamicMetadata& propertyMetaData);
 
-    //! Convert and assign editor dynamic property configuration fields to material property meta data 
+    //! Convert and assign editor dynamic property configuration fields to material property meta data
     void ConvertToPropertyMetaData(AZ::RPI::MaterialPropertyDynamicMetadata& propertyMetaData, const AtomToolsFramework::DynamicPropertyConfig& propertyConfig);
 
     //! Compare equality of data types and values of editor property stored in AZStd::any
@@ -44,16 +44,20 @@ namespace AtomToolsFramework
 
     //! Convert the property value into the format that will be stored in the source data
     //! This is primarily needed to support conversions of special types like enums and images
+    //! @param exportPath absolute path of the file being saved
+    //! @param propertyDefinition describes type information and other details about propertyValue
+    //! @param propertyValue the value being converted before saving
     bool ConvertToExportFormat(
         const AZStd::string& exportPath,
         const AZ::RPI::MaterialTypeSourceData::PropertyDefinition& propertyDefinition,
         AZ::RPI::MaterialPropertyValue& propertyValue);
 
     //! Generate a file path from the exported file to the external reference.
-    //! This function is to support copying or moving a folder containing materials, models, and textures without modifying the files. The
+    //! This function returns a relative path from the export file to the reference file.
-    //! general case returns a relative path from the export file to the reference file. If the relative path is too different or distant
+    //! If the relative path is too different or distant from the export path then we return the asset folder relative path.
-    //! from the export path then we return the asset folder relative path. An alternate solution would be to only use export folder
+    //! @param exportPath absolute path of the file being saved
-    //! relative paths if the referenced path is in the same folder or a sub folder the assets are not generally packaged like that.
+    //! @param referencePath absolute path of a file that will be treated as an external reference
+    //! @param maxPathDepth the maximum relative depth or number of parent or child folders between the export path and the reference path
     AZStd::string GetExteralReferencePath(
         const AZStd::string& exportPath, const AZStd::string& referencePath, const uint32_t maxPathDepth = 2);
 

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

@@ -658,8 +658,8 @@ namespace MaterialEditor
                 return false;
             }
 
-            // We must also always load the material type data for a complete, ordered set of the
+            // We always need the absolute path for the material type and parent material to load source data and resolving
-            // groups and properties that will be needed for comparison and building the inspector
+            // relative paths when saving. This will convert and store them as absolute paths for use within the document.
             if (!m_materialSourceData.m_parentMaterial.empty())
             {
                 m_materialSourceData.m_parentMaterial =
@@ -671,6 +671,7 @@ namespace MaterialEditor
                 m_materialSourceData.m_materialType = AssetUtils::ResolvePathReference(m_absolutePath, m_materialSourceData.m_materialType);
             }
 
+            // Load the material type source data which provides the layout and default values of all of the properties
             auto materialTypeOutcome = MaterialUtils::LoadMaterialTypeSourceData(m_materialSourceData.m_materialType);
             if (!materialTypeOutcome.IsSuccess())
             {
@@ -687,7 +688,9 @@ namespace MaterialEditor
         }
         else if (AzFramework::StringFunc::Path::IsExtension(m_absolutePath.c_str(), MaterialTypeSourceData::Extension))
         {
-            // Load the material type source data, which will be used for enumerating properties and building material source data
+            // A material document can be created or loaded from material or material type source data. If we are attempting to load
+            // material type source data then the material source data object can be created just by referencing the document path as the
+            // material type path.
             auto materialTypeOutcome = MaterialUtils::LoadMaterialTypeSourceData(m_absolutePath);
             if (!materialTypeOutcome.IsSuccess())
             {
@@ -696,8 +699,7 @@ namespace MaterialEditor
             }
             m_materialTypeSourceData = materialTypeOutcome.GetValue();
 
-            // The document represents a material, not a material type.
+            // We are storing absolute paths in the loaded version of the source data so that the files can be resolved at all times.
-            // If the input data is a material type file we have to generate the material source data by referencing it.
             m_materialSourceData.m_materialType = m_absolutePath;
             m_materialSourceData.m_parentMaterial.clear();
         }