V15/xml comments (#713)

* null reference fix.

* comments to reduce the build warnings.

* update code QL, to only run on main.

* Some more comments

* final few ?

.github/workflows/codeql.yml

@@ -14,8 +14,6 @@ name: "CodeQL"
 on:
   push:
     branches: ["*/main"]
-  pull_request:
-    branches: ["*/main"]
 
 jobs:
   analyze:

uSync.BackOffice/Extensions/HandlerSettingsExtensions.cs

@@ -2,12 +2,21 @@
 
 namespace uSync.BackOffice.Extensions;
 
+/// <summary>
+///  helpers for the config of handlers.
+/// </summary>
 public static class HandlerSettingsExtensions
 {
+    /// <summary>
+    ///  is the handler setup for creation of new items only ?
+    /// </summary>
     public static bool IsCreateOnly(this HandlerSettings settings)
         => settings.GetSetting(Core.uSyncConstants.DefaultSettings.CreateOnly, Core.uSyncConstants.DefaultSettings.CreateOnly_Default)
             || settings.GetSetting(Core.uSyncConstants.DefaultSettings.OneWay, Core.uSyncConstants.DefaultSettings.CreateOnly_Default);
 
+    /// <summary>
+    ///  are deletes allowed with the creation of new items. 
+    /// </summary>
     public static bool AllowCreateOnlyDeletes(this HandlerSettings settings)
         => settings.GetSetting(Core.uSyncConstants.DefaultSettings.AllowCreateOnlyDeletes, Core.uSyncConstants.DefaultSettings.AllowCreateOnlyDeletes_Default);
 }

uSync.BackOffice/Models/SyncFinalActionRequest.cs

@@ -5,13 +5,39 @@
 
 namespace uSync.BackOffice.Models;
 
+/// <summary>
+///  request model for things that happen at the end of the process.
+/// </summary>
 public class SyncFinalActionRequest
 {
+    /// <summary>
+    ///  request Id
+    /// </summary>
     public required Guid RequestId { get; set; }
+
+    /// <summary>
+    ///  current handler action (e.g import, export)
+    /// </summary>
     public HandlerActions HandlerAction { get; set; } = HandlerActions.None;
+
+    /// <summary>
+    ///  options for the action
+    /// </summary>
     public required SyncActionOptions ActionOptions { get; set; }
+
+    /// <summary>
+    ///  list of the results for the process
+    /// </summary>
     public IEnumerable<uSyncAction> Actions { get; set; } = [];
+
+    /// <summary>
+    ///  user of the person who triggered the process
+    /// </summary>
     public string? Username { get; set; }
+
+    /// <summary>
+    ///  callbacks for signalR ui refreshing. 
+    /// </summary>
     public uSyncCallbacks? Callbacks { get; set; }
 }
 

uSync.BackOffice/SyncHandlers/SyncHandlerBase.cs

@@ -127,6 +127,7 @@ public virtual async Task<IEnumerable<uSyncAction>> ProcessCleanActionsAsync(str
     protected override async Task<IEnumerable<uSyncAction>> DeleteMissingItemsAsync(TObject parent, IEnumerable<Guid> keysToKeep, bool reportOnly)
         => await DeleteMissingItemsAsync(parent?.Key ?? Guid.Empty, keysToKeep, reportOnly);
 
+    /// <inheritdoc/>
     protected override async Task<IEnumerable<uSyncAction>> DeleteMissingItemsAsync(Guid key, IEnumerable<Guid> keysToKeep, bool reportOnly)
     {
         var items = (await GetChildItemsAsync(key)).ToArray();
@@ -169,6 +170,7 @@ protected override async Task<IEnumerable<uSyncAction>> DeleteMissingItemsAsync(
         return actions;
     }
 
+    /// <inheritdoc/>
     protected override async Task<IEnumerable<IEntity>> GetChildItemsAsync(IEntity? parent)
         => await GetChildItemsAsync(parent?.Key ?? Guid.Empty);
 
@@ -192,6 +194,9 @@ virtual protected IEnumerable<IEntity> GetChildItems(int parent)
         return GetChildItemsAsync(entity.Key).Result;
     }
 
+    /// <summary>
+    ///  Get all child items beneath a given item
+    /// </summary>
     [Obsolete("use GetChildItemsAsync will be removed in v16")]
     virtual protected IEnumerable<IEntity> GetChildItems(int parent, UmbracoObjectTypes objectType)
     {
@@ -217,12 +222,18 @@ virtual protected IEnumerable<IEntity> GetChildItems(int parent, UmbracoObjectTy
 
     }
 
+    /// <summary>
+    ///  Get all child items beneath a given item
+    /// </summary>
     virtual protected async Task<IEnumerable<IEntity>> GetChildItemsAsync(Guid key)
     {
         if (this.ItemObjectType == UmbracoObjectTypes.Unknown) return [];
         return await GetChildItemsAsync(key, this.ItemObjectType);
     }
 
+    /// <summary>
+    ///  Get all child items beneath a given item
+    /// </summary>
     virtual protected async Task<IEnumerable<IEntity>> GetChildItemsAsync(Guid key, UmbracoObjectTypes objectType)
     {
         var cacheKey = $"{GetCacheKeyBase()}_parent_{key}_{objectType}";
@@ -233,6 +244,9 @@ virtual protected async Task<IEnumerable<IEntity>> GetChildItemsAsync(Guid key,
         }, null) ?? [];
     }
 
+    /// <summary>
+    ///  Get all child items beneath a given key, for a given object type
+    /// </summary>
     private async Task<IEnumerable<IEntity>> GetEntityChildrenAsync(Guid key, UmbracoObjectTypes objectType)
     {
         // logger.LogDebug("Cache miss [{key}]", cacheKey);
@@ -267,6 +281,9 @@ virtual protected IEnumerable<IEntity> GetFolders(int parent)
         return [];
     }
 
+    /// <summary>
+    /// Get all 'folders' beneath a given item (usually these are Container items)
+    /// </summary>
     virtual protected async Task<IEnumerable<IEntity>> GetFoldersAsync(Guid key)
     {
         if (this.ItemContainerType == UmbracoObjectTypes.Unknown)
@@ -283,24 +300,27 @@ protected override IEnumerable<IEntity> GetFolders(IEntity? parent)
         return GetFolders(parent.Id);
     }
 
+    /// <inheritdoc/>
     protected override async Task<IEnumerable<IEntity>> GetFoldersAsync(IEntity? parent)
     {
         if (parent is null) return await GetFoldersAsync(Guid.Empty);
         return await GetFoldersAsync(parent.Key);
     }
 
+    /// <inheritdoc/>
     protected override async Task<TObject?> GetFromServiceAsync(IEntity? entity)
         => entity is null ? default : await GetFromServiceAsync(entity.Key);
 
     /// <summary>
     ///  for backwards compatibility up the tree.
     /// </summary>
-    /// <param name="id"></param>
-    /// <returns></returns>
     [Obsolete("Use GetFromServiceAsync will be removed in v16")]
     public bool HasChildren(int id)
         => true;
 
+    /// <summary>
+    ///  for backwards compatibility up the tree.
+    /// </summary>
     public async Task<bool> HasChildrenAsync(Guid key)
         => (await GetFoldersAsync(key)).Any() || (await GetChildItemsAsync(key)).Any();
 

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>();
@@ -107,8 +110,14 @@ private static bool IsContainer(Guid guid)
     [Obsolete("Delete by key - will be removed in v16")]
     virtual protected void DeleteFolder(int id) { }
 
+    /// <summary>
+    /// delete a container
+    /// </summary>
     abstract protected Task DeleteFolderAsync(Guid key);
 
+    /// <summary>
+    ///  process things post import (at the end when everything has been imported)
+    /// </summary>
     public virtual async Task<IEnumerable<uSyncAction>> ProcessPostImportAsync(IEnumerable<uSyncAction> actions, HandlerSettings config)
     {
         if (actions == null || !actions.Any()) return [];
@@ -144,6 +153,10 @@ protected IEnumerable<uSyncAction> UpdateFolder(int folderId, string folder, Han
     protected IEnumerable<uSyncAction> UpdateFolder(int folderId, string[] folders, HandlerSettings config)
         => [];
 
+    /// <summary>
+    ///  will resave everything in a folder (and beneath)
+    ///  we need to this when it's renamed
+    /// </summary>
     protected async Task<IEnumerable<uSyncAction>> UpdateFolderAsync(Guid folderKey, string[] folders, HandlerSettings config)
     {
         if (this.serializer is SyncContainerSerializerBase<TObject> containerSerializer)
@@ -188,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;
@@ -204,6 +216,9 @@ public virtual Task HandleAsync(EntityContainerSavedNotification notification, C
     }
 
 
+    /// <summary>
+    ///  Handle container renamed events
+    /// </summary>
     public virtual async Task HandleAsync(EntityContainerRenamedNotification notification, CancellationToken cancellationToken)
     {
         if (!ShouldProcessEvent()) return;