Some more comments

uSync.BackOffice/SyncHandlers/SyncHandlerContainerBase.cs

@@ -64,6 +64,9 @@ protected SyncHandlerContainerBase(
     protected IEnumerable<uSyncAction> CleanFolders(int parent)
         => [];
 
+    /// <summary>
+    ///  Removes any empty 'containers' after import 
+    /// </summary>
     protected async Task<IEnumerable<uSyncAction>> CleanFoldersAsync(Guid parentKey)
     {
         var actions = new List<uSyncAction>();
@@ -198,7 +201,6 @@ protected async Task<IEnumerable<uSyncAction>> UpdateFolderAsync(Guid folderKey,
     /// <summary>
     ///  Handle container saving events
     /// </summary>
-    /// <param name="notification"></param>
     public virtual Task HandleAsync(EntityContainerSavedNotification notification, CancellationToken cancellationToken)
     {
         return Task.CompletedTask;

uSync.BackOffice/SyncHandlers/SyncHandlerRoot.cs

@@ -387,6 +387,9 @@ private async Task PerformImportCleanAsync(List<string> cleanMarkers, List<uSync
     public virtual IEnumerable<uSyncAction> Import(string filePath, HandlerSettings config, SerializerFlags flags)
         => ImportAsync(filePath, config, new uSyncImportOptions { Flags = flags }).Result;
 
+    /// <summary>
+    ///  Import a single item, from the .config file supplied
+    /// </summary>
     public virtual async Task<IEnumerable<uSyncAction>> ImportAsync(string filePath, HandlerSettings config, uSyncImportOptions options)
     {
         try
@@ -702,6 +705,9 @@ protected IList<Guid> GetFolderKeys(string folder, bool flat)
     protected TObject? GetCleanParent(string file)
         => GetCleanParentAsync(file).Result;
 
+    /// <summary>
+    ///  Get the parent item of the clean file (so we can check if the folder has any versions of this item in it)
+    /// </summary>
     protected async Task<TObject?> GetCleanParentAsync(string file)
     {
         var node = XElement.Load(file);
@@ -721,6 +727,13 @@ protected IList<Guid> GetFolderKeys(string folder, bool flat)
     protected virtual IEnumerable<uSyncAction> DeleteMissingItems(TObject parent, IEnumerable<Guid> keysToKeep, bool reportOnly)
         => DeleteMissingItemsAsync(parent, keysToKeep, reportOnly).Result;
 
+    /// <summary>
+    ///  remove an items that are not listed in the GUIDs to keep
+    /// </summary>
+    /// <param name="parent">parent item that all keys will be under</param>
+    /// <param name="keysToKeep">list of GUIDs of items we don't want to delete</param>
+    /// <param name="reportOnly">will just report what would happen (doesn't do the delete)</param>
+    /// <returns>list of delete actions</returns>
     protected abstract Task<IEnumerable<uSyncAction>> DeleteMissingItemsAsync(TObject parent, IEnumerable<Guid> keysToKeep, bool reportOnly);
 
     /// <summary>
@@ -734,6 +747,13 @@ protected virtual IEnumerable<uSyncAction> DeleteMissingItems(TObject parent, IE
     protected virtual IEnumerable<uSyncAction> DeleteMissingItems(int parentId, IEnumerable<Guid> keysToKeep, bool reportOnly)
         => [];
 
+    /// <summary>
+    /// Remove an items that are not listed in the GUIDs to keep.
+    /// </summary>
+    /// <param name="parentId">parent item that all keys will be under</param>
+    /// <param name="keysToKeep">list of GUIDs of items we don't want to delete</param>
+    /// <param name="reportOnly">will just report what would happen (doesn't do the delete)</param>
+    /// <returns>list of delete actions</returns>
     protected virtual Task<IEnumerable<uSyncAction>> DeleteMissingItemsAsync(Guid key, IEnumerable<Guid> keysToKeep, bool reportOnly)
         => Task.FromResult(Enumerable.Empty<uSyncAction>());
 
@@ -750,6 +770,9 @@ protected virtual IEnumerable<string> GetImportFiles(string folder)
     virtual protected bool ShouldImport(XElement node, HandlerSettings config)
         => ShouldImportAsync(node, config).Result;
 
+    /// <summary>
+    ///  check to see if this element should be imported as part of the process.
+    /// </summary>
     virtual protected async Task<bool> ShouldImportAsync(XElement node, HandlerSettings config)
     {
         // if createOnly is on, then we only create things that are not already there. 
@@ -793,6 +816,10 @@ virtual protected async Task<bool> ShouldImportAsync(XElement node, HandlerSetti
     /// </summary>
     [Obsolete("Use ShouldExportAsync will be removed in v16")]
     virtual protected bool ShouldExport(XElement node, HandlerSettings config) => true;
+
+    /// <summary>
+    ///  Check to see if this element should be exported. 
+    /// </summary>
     virtual protected Task<bool> ShouldExportAsync(XElement node, HandlerSettings config) => Task.FromResult(true);
 
     #endregion
@@ -835,10 +862,16 @@ virtual public IEnumerable<uSyncAction> ExportAll(TContainer? parent, string fol
     virtual public IEnumerable<uSyncAction> ExportAll(TContainer? parent, string[] folders, HandlerSettings config, SyncUpdateCallback? callback)
         => ExportAllAsync(parent, folders, config, callback).Result;
 
+    /// <summary>
+    /// Export all items to a give folder on the disk
+    /// </summary>
     virtual public async Task<IEnumerable<uSyncAction>> ExportAllAsync(string[] folders, HandlerSettings settings, SyncUpdateCallback? callback)
         => await ExportAllAsync(default, folders, settings, callback);
 
 
+    /// <summary>
+    /// Export all items to a give folder on the disk
+    /// </summary>
     virtual public async Task<IEnumerable<uSyncAction>> ExportAllAsync(TContainer? parent, string[] folders, HandlerSettings config, SyncUpdateCallback? callback)
     {
         var actions = new List<uSyncAction>();
@@ -881,17 +914,21 @@ virtual public async Task<IEnumerable<uSyncAction>> ExportAllAsync(TContainer? p
     [Obsolete("use GetFoldersAsync will be removed in v16")]
     virtual protected IEnumerable<TContainer> GetChildItems(TContainer? parent) => [];
 
+    /// <summary>
+    /// Fetch all child items beneath a given container 
+    /// </summary>
     abstract protected Task<IEnumerable<TContainer>> GetChildItemsAsync(TContainer? parent);
 
     /// <summary>
     /// Fetch all child items beneath a given folder
     /// </summary>
-    /// <param name="parent"></param>
-    /// <returns></returns>
     [Obsolete("use GetFoldersAsync will be removed in v16")]
     virtual protected IEnumerable<TContainer> GetFolders(TContainer? parent)
         => GetFoldersAsync(parent).Result;
 
+    /// <summary>
+    /// Fetch all child items beneath a given folder
+    /// </summary>
     abstract protected Task<IEnumerable<TContainer>> GetFoldersAsync(TContainer? parent);
 
     /// <summary>
@@ -901,6 +938,9 @@ virtual protected IEnumerable<TContainer> GetFolders(TContainer? parent)
     public bool HasChildren(TContainer item)
         => GetFolders(item).Any() || GetChildItems(item).Any();
 
+    /// <summary>
+    /// Does this container have any children 
+    /// </summary>
     public virtual async Task<bool> HasChildrenAsync(TContainer item)
         => (await GetFoldersAsync(item)).Any() || (await GetChildItemsAsync(item)).Any();
 
@@ -966,6 +1006,9 @@ virtual public IEnumerable<uSyncAction> Export(TObject item, string folder, Hand
     virtual public IEnumerable<uSyncAction> Export(TObject item, string[] folders, HandlerSettings config)
         => ExportAsync(item, folders, config).Result;
 
+    /// <summary>
+    /// Export a given item to disk
+    /// </summary>
     virtual public async Task<IEnumerable<uSyncAction>> ExportAsync(TObject item, string[] folders, HandlerSettings config)
     {
         if (item == null)
@@ -1016,6 +1059,12 @@ virtual public async Task<IEnumerable<uSyncAction>> ExportAsync(TObject item, st
     protected virtual SyncAttempt<XElement> Export_DoExport(TObject item, string filename, string[] folders, HandlerSettings config)
         => Export_DoExportAsync(item, filename, folders, config).Result;
 
+    /// <summary>
+    ///  Do the meat of the export 
+    /// </summary>
+    /// <remarks>
+    ///  inheriting this method, means you don't have to repeat all the checks in child handlers. 
+    /// </remarks>
     protected virtual async Task<SyncAttempt<XElement>> Export_DoExportAsync(TObject item, string filename, string[] folders, HandlerSettings config)
     {
         var attempt = await SerializeItemAsync(item, new SyncSerializerOptions(config.Settings));