Added some comments

Code/Framework/AzToolsFramework/AzToolsFramework/Prefab/Instance/InstanceUpdateExecutor.cpp

@@ -117,6 +117,7 @@ namespace AzToolsFramework
                                     "Could not find Template using Id '%llu'. Unable to update Instance.",
                                     currentTemplateId);
 
+                                // Remove the instance from update queue if it's corresponding template couldn't be found
                                 isUpdateSuccessful = false;
                                 m_instancesUpdateQueue.pop();
                                 continue;
@@ -127,6 +128,8 @@ namespace AzToolsFramework
 
                         if (findInstancesResult.find(instanceToUpdate) == findInstancesResult.end())
                         {
+                            // Since nested instances get reconstructed during propgation, remove any nested instance that no longer
+                            // maps to a template.
                             isUpdateSuccessful = false;
                             m_instancesUpdateQueue.pop();
                             continue;
@@ -155,6 +158,8 @@ namespace AzToolsFramework
 
                     for (auto entityIdIterator = selectedEntityIds.begin(); entityIdIterator != selectedEntityIds.end(); entityIdIterator++)
                     {
+                        // Since entities get recreated during propagation, we need to check whether the entities correspoding to the list
+                        // of selected entity ids are present or not.
                         AZ::Entity* entity = GetEntityById(*entityIdIterator);
                         if (entity == nullptr)
                         {

Code/Framework/AzToolsFramework/AzToolsFramework/Prefab/PrefabPublicHandler.cpp

@@ -121,7 +121,7 @@ namespace AzToolsFramework
                     commonRootEntityOwningInstance->get(), "Update prefab instance", commonRootInstanceDomBeforeCreate, undoBatch.GetUndoBatch());
 
                 CreateLink(
-                    topLevelEntities, instanceToCreate->get(), commonRootEntityOwningInstance->get(), undoBatch.GetUndoBatch(),
+                    topLevelEntities, instanceToCreate->get(), commonRootEntityOwningInstance->get().GetTemplateId(), undoBatch.GetUndoBatch(),
                     commonRootEntityId);
                 AZ::EntityId containerEntityId = instanceToCreate->get().GetContainerEntityId();
 
@@ -182,10 +182,10 @@ namespace AzToolsFramework
         }
 
         void PrefabPublicHandler::CreateLink(
-            const EntityList& topLevelEntities, Instance& instanceToAdd, Instance& parentInstance, UndoSystem::URSequencePoint* undoBatch,
-            AZ::EntityId commonRootEntityId)
+            const EntityList& topLevelEntities, Instance& sourceInstance, TemplateId targetTemplateId,
+            UndoSystem::URSequencePoint* undoBatch, AZ::EntityId commonRootEntityId)
         {
-            AZ::EntityId containerEntityId = instanceToAdd.GetContainerEntityId();
+            AZ::EntityId containerEntityId = sourceInstance.GetContainerEntityId();
             AZ::Entity* containerEntity = GetEntityById(containerEntityId);
             Prefab::PrefabDom containerEntityDomBefore;
             m_instanceToTemplateInterface->GenerateDomForEntity(containerEntityDomBefore, *containerEntity);
@@ -210,7 +210,7 @@ namespace AzToolsFramework
             m_instanceToTemplateInterface->AppendEntityAliasToPatchPaths(patch, containerEntityId);
 
             PrefabUndoHelpers::CreateLink(
-                instanceToAdd.GetTemplateId(), parentInstance.GetTemplateId(), patch, instanceToAdd.GetInstanceAlias(),
+                sourceInstance.GetTemplateId(), targetTemplateId, patch, sourceInstance.GetInstanceAlias(),
                 undoBatch);
 
             // Update the cache - this prevents these changes from being stored in the regular undo/redo nodes

Code/Framework/AzToolsFramework/AzToolsFramework/Prefab/PrefabPublicHandler.h

@@ -69,10 +69,29 @@ namespace AzToolsFramework
             InstanceOptionalReference GetOwnerInstanceByEntityId(AZ::EntityId entityId) const;
             bool EntitiesBelongToSameInstance(const EntityIdList& entityIds) const;
 
+            /**
+             * Creates a link between the templates of an instance and its parent.
+             * 
+             * \param topLevelEntities The list of entities that are immediate children of container entity of instance.
+             * \param sourceInstance The instance that corresponds to the source template of the link.
+             * \param targetInstance The id of the target template.
+             * \param undoBatch The undo batch to set as parent for this create link action.
+             * \param commonRootEntityId The id of the entity that the source instance should be parented under.
+             */
             void CreateLink(
-                const EntityList& topLevelEntities, Instance& instanceToAdd, Instance& parentInstance,
+                const EntityList& topLevelEntities, Instance& sourceInstance, TemplateId targetTemplateId,
                 UndoSystem::URSequencePoint* undoBatch, AZ::EntityId commonRootEntityId);
 
+            /**
+             * Given a list of entityIds, finds the prefab instance that owns the common root entity of the entityIds.
+             * 
+             * \param entityIds The list of entity ids.
+             * \param inputEntityList The list of entities corresponding to the entity ids.
+             * \param topLevelEntities The list of entities that are immediate children of the common root entity.
+             * \param commonRootEntityId The entity id of the common root entity of all the entityIds.
+             * \param commonRootEntityOwningInstance The owning instance of the common root entity.
+             * \return PrefabOperationResult indicating whether the action was successful or not.
+             */
             PrefabOperationResult FindCommonRootOwningInstance(
                 const AZStd::vector<AZ::EntityId>& entityIds, EntityList& inputEntityList, EntityList& topLevelEntities,
                 AZ::EntityId& commonRootEntityId, InstanceOptionalReference& commonRootEntityOwningInstance);