CQ: Add comments

Author: XTorLukas

src/Files.App/Data/Contracts/IRealTimeControl.cs

@@ -3,10 +3,19 @@
 
 namespace Files.App.Data.Contracts
 {
+	/// <summary>
+	/// Defines an interface for real-time control components that manage content layout updates.
+	/// </summary>
 	internal interface IRealTimeControl
 	{
+		/// <summary>
+		/// Initializes the content layout for the control.
+		/// </summary>
 		void InitializeContentLayout();
 
+		/// <summary>
+		/// Updates the content layout of the control.
+		/// </summary>
 		void UpdateContentLayout();
 	}
 }

src/Files.App/Data/Contracts/IRealTimeLayoutService.cs

@@ -3,18 +3,46 @@
 
 namespace Files.App.Data.Contracts
 {
+	/// <summary>
+	/// Provides an interface for managing real-time layout updates and related operations.
+	/// </summary>
 	public interface IRealTimeLayoutService
 	{
-
+		/// <summary>
+		/// Gets the current flow direction for layout (e.g., LeftToRight or RightToLeft).
+		/// </summary>
 		FlowDirection FlowDirection { get; }
+
+		/// <summary>
+		/// Adds a callback to be executed when a specific target requires updates.
+		/// </summary>
+		/// <param name="target">The target object for which the callback is registered.</param>
+		/// <param name="callback">The action to execute during updates.</param>
 		void AddCallback(object target, Action callback);
 
+		/// <summary>
+		/// Updates the content layout of the specified framework element.
+		/// </summary>
+		/// <param name="frameworkElement">The framework element to update.</param>
 		void UpdateContent(FrameworkElement frameworkElement);
 
+		/// <summary>
+		/// Updates the content layout of the specified window.
+		/// </summary>
+		/// <param name="window">The window whose content layout needs updating.</param>
 		void UpdateContent(Window window);
 
+		/// <summary>
+		/// Updates the culture settings for the layout.
+		/// </summary>
+		/// <param name="culture">The culture information to apply.</param>
 		void UpdateCulture(CultureInfo culture);
 
+		/// <summary>
+		/// Updates the title bar of the specified window.
+		/// </summary>
+		/// <param name="window">The window whose title bar needs updating.</param>
+		/// <returns>True if the title bar was successfully updated; otherwise, false.</returns>
 		bool UpdateTitleBar(Window window);
 	}
 }

src/Files.App/Data/Contracts/IRealTimeWindow.cs

@@ -3,10 +3,19 @@
 
 namespace Files.App.Data.Contracts
 {
+	/// <summary>
+	/// Defines an interface for real-time window components that manage content layout updates.
+	/// </summary>
 	internal interface IRealTimeWindow
 	{
+		/// <summary>
+		/// Initializes the content layout for the window.
+		/// </summary>
 		void InitializeContentLayout() { }
 
+		/// <summary>
+		/// Updates the content layout of the window.
+		/// </summary>
 		void UpdateContentLayout() { }
 	}
 }

src/Files.App/Services/Content/RealTimeLayoutService.cs

@@ -7,12 +7,26 @@
 
 namespace Files.App.Services.Content
 {
+	/// <summary>
+	/// Provides a service to manage real-time layout updates, including content layout and title bar updates,
+	/// while supporting flow direction based on the current culture.
+	/// </summary>
 	internal sealed class RealTimeLayoutService : IRealTimeLayoutService
 	{
+		/// <summary>
+		/// List of weak references to target objects and their associated callbacks.
+		/// </summary>
 		private readonly List<(WeakReference<object> Reference, Action Callback)> _callbacks = [];
 
+		/// <summary>
+		/// Gets the current flow direction based on the current UI culture (RightToLeft or LeftToRight).
+		/// </summary>
 		public FlowDirection FlowDirection => CultureInfo.CurrentUICulture.TextInfo.IsRightToLeft ? FlowDirection.RightToLeft : FlowDirection.LeftToRight;
 
+		/// <summary>
+		/// Updates the culture for the layout service and invokes the necessary callbacks if the flow direction changes.
+		/// </summary>
+		/// <param name="culture">The new culture information to apply.</param>
 		public void UpdateCulture(CultureInfo culture)
 		{
 			FlowDirection tmp = FlowDirection;
@@ -24,6 +38,11 @@ public void UpdateCulture(CultureInfo culture)
 				InvokeCallbacks();
 		}
 
+		/// <summary>
+		/// Registers a callback to be invoked when the layout needs to be updated for the specified target.
+		/// </summary>
+		/// <param name="target">The target object to associate with the callback.</param>
+		/// <param name="callback">The callback to invoke when the layout is updated.</param>
 		public void AddCallback(object target, Action callback)
 		{
 			var weakReference = new WeakReference<object>(target);
@@ -36,6 +55,11 @@ public void AddCallback(object target, Action callback)
 				element.Unloaded += (sender, args) => RemoveCallback(target);
 		}
 
+		/// <summary>
+		/// Updates the title bar layout of the specified window based on the current flow direction.
+		/// </summary>
+		/// <param name="window">The window whose title bar layout needs updating.</param>
+		/// <returns>True if the title bar layout was successfully updated; otherwise, false.</returns>
 		public bool UpdateTitleBar(Window window)
 		{
 			try
@@ -58,23 +82,38 @@ public bool UpdateTitleBar(Window window)
 			return true;
 		}
 
+		/// <summary>
+		/// Updates the content layout of the specified window to match the current flow direction.
+		/// </summary>
+		/// <param name="window">The window whose content layout needs updating.</param>
 		public void UpdateContent(Window window)
 		{
 			if (window.Content is FrameworkElement frameworkElement)
 				frameworkElement.FlowDirection = FlowDirection;
 		}
 
+		/// <summary>
+		/// Updates the content layout of the specified framework element to match the current flow direction.
+		/// </summary>
+		/// <param name="frameworkElement">The framework element whose content layout needs updating.</param>
 		public void UpdateContent(FrameworkElement frameworkElement)
 		{
 			frameworkElement.FlowDirection = FlowDirection;
 		}
 
+		/// <summary>
+		/// Removes the callback associated with the specified target.
+		/// </summary>
+		/// <param name="target">The target object whose callback needs to be removed.</param>
 		private void RemoveCallback(object target)
 		{
 			_callbacks.RemoveAll(item =>
 				item.Reference.TryGetTarget(out var targetObject) && targetObject == target);
 		}
 
+		/// <summary>
+		/// Invokes all registered callbacks for targets that are still valid.
+		/// </summary>
 		private void InvokeCallbacks()
 		{
 			_callbacks.Where(item =>

src/Files.Core.SourceGenerator/Constants.cs

@@ -99,16 +99,39 @@ internal class StringsPropertyGenerator
 			internal const char ConstantSeparator = '/';
 		}
 
+		/// <summary>
+		/// Provides functionality for generating real-time layout specifications.
+		/// </summary>
 		internal class RealTimeLayoutGenerator
 		{
+			/// <summary>
+			/// The name of the real-time specification window.
+			/// </summary>
 			internal const string SpecificationWindowName = "IRealTimeWindow";
 
+			/// <summary>
+			/// The name of the real-time specification control.
+			/// </summary>
 			internal const string SpecificationControlName = "IRealTimeControl";
 
+			/// <summary>
+			/// Specifies the types of real-time layout specifications.
+			/// </summary>
 			internal enum SpecificationType
 			{
+				/// <summary>
+				/// No specification type.
+				/// </summary>
 				None = 0,
+
+				/// <summary>
+				/// Specifies a window layout.
+				/// </summary>
 				Window,
+
+				/// <summary>
+				/// Specifies a control layout.
+				/// </summary>
 				Control
 			}
 		}

src/Files.Core.SourceGenerator/Generators/RealTimeLayoutGenerator.cs

@@ -5,9 +5,17 @@
 
 namespace Files.Core.SourceGenerator.Generators
 {
+	/// <summary>
+	/// Generates additional source code for classes based on their inheritance from specific types 
+	/// (e.g., IRealTimeWindow or IRealTimeControl).
+	/// </summary>
 	[Generator]
 	public class RealTimeLayoutGenerator : IIncrementalGenerator
 	{
+		/// <summary>
+		/// Initializes the incremental source generator with context-specific configuration.
+		/// </summary>
+		/// <param name="context">The incremental generator initialization context.</param>
 		public void Initialize(IncrementalGeneratorInitializationContext context)
 		{
 			var candidateClasses = context.SyntaxProvider
@@ -28,6 +36,11 @@ public void Initialize(IncrementalGeneratorInitializationContext context)
 			});
 		}
 
+		/// <summary>
+		/// Determines if the syntax node is a valid candidate for generation.
+		/// </summary>
+		/// <param name="syntaxNode">The syntax node to evaluate.</param>
+		/// <returns>True if the node is a valid class candidate; otherwise, false.</returns>
 		private static bool IsValidCandidate(SyntaxNode syntaxNode)
 		{
 			if (syntaxNode is ClassDeclarationSyntax classDeclaration)
@@ -38,6 +51,11 @@ private static bool IsValidCandidate(SyntaxNode syntaxNode)
 			return false;
 		}
 
+		/// <summary>
+		/// Retrieves a class declaration and its specification type if it matches the criteria.
+		/// </summary>
+		/// <param name="context">The syntax context for the generator.</param>
+		/// <returns>A tuple containing the class declaration and its specification type, or null if no match.</returns>
 		private static (ClassDeclarationSyntax Class, SpecificationType Type)? GetCandidateClass(GeneratorSyntaxContext context)
 		{
 			var classDeclaration = (ClassDeclarationSyntax)context.Node;
@@ -60,6 +78,13 @@ private static (ClassDeclarationSyntax Class, SpecificationType Type)? GetCandid
 			return null;
 		}
 
+		/// <summary>
+		/// Generates the source code for a class based on the provided namespace, class name, and type.
+		/// </summary>
+		/// <param name="namespaceName">The namespace of the class.</param>
+		/// <param name="className">The name of the class.</param>
+		/// <param name="type">The type of the specification (Window or Control).</param>
+		/// <returns>The generated source code as a string.</returns>
 		private static string GenerateClass(string namespaceName, string className, SpecificationType type)
 		{
 			// Namespace
@@ -111,6 +136,11 @@ private static string GenerateClass(string namespaceName, string className, Spec
 			return compilationUnit.ToFullString();
 		}
 
+		/// <summary>
+		/// Creates the body statements for the InitializeContentLayout method.
+		/// </summary>
+		/// <param name="type">The type of the specification (Window or Control).</param>
+		/// <returns>A collection of statements for the method body.</returns>
 		private static IEnumerable<StatementSyntax> CreateInitializeContentLayoutBody(SpecificationType type)
 		{
 			var statements = new List<StatementSyntax>
@@ -128,6 +158,11 @@ private static IEnumerable<StatementSyntax> CreateInitializeContentLayoutBody(Sp
 			return statements;
 		}
 
+		/// <summary>
+		/// Creates the body statements for the UpdateContentLayout method.
+		/// </summary>
+		/// <param name="type">The type of the specification (Window or Control).</param>
+		/// <returns>A collection of statements for the method body.</returns>
 		private static IEnumerable<StatementSyntax> CreateUpdateContentLayoutBody(SpecificationType type)
 		{
 			var statements = new List<StatementSyntax>();
@@ -140,6 +175,11 @@ private static IEnumerable<StatementSyntax> CreateUpdateContentLayoutBody(Specif
 			return statements;
 		}
 
+		/// <summary>
+		/// Retrieves the namespace of a given syntax node.
+		/// </summary>
+		/// <param name="node">The syntax node to evaluate.</param>
+		/// <returns>The namespace name as a string.</returns>
 		private static string GetNamespace(SyntaxNode node)
 		{
 			while (node != null)