Add XML documentation comments for public classes and methods [Fixes #42]

csharp/Platform.Data/ILinksExtensions.cs

@@ -18,8 +18,48 @@ namespace Platform.Data
     /// </summary>
     public static class ILinksExtensions
     {
+        /// <summary>
+        /// <para>
+        /// Creates a new link with no specific content.
+        /// </para>
+        /// <para></para>
+        /// </summary>
+        /// <typeparam name="TLinkAddress">
+        /// <para>The type used to represent link addresses.</para>
+        /// <para></para>
+        /// </typeparam>
+        /// <param name="links">
+        /// <para>The links storage to create the link in.</para>
+        /// <para></para>
+        /// </param>
+        /// <returns>
+        /// <para>The address of the created link.</para>
+        /// <para></para>
+        /// </returns>
         public static TLinkAddress Create<TLinkAddress>(this ILinks<TLinkAddress, LinksConstants<TLinkAddress>> links) where TLinkAddress : IUnsignedNumber<TLinkAddress> => links.Create(null);
 
+        /// <summary>
+        /// <para>
+        /// Creates a new link with the specified content.
+        /// </para>
+        /// <para></para>
+        /// </summary>
+        /// <typeparam name="TLinkAddress">
+        /// <para>The type used to represent link addresses.</para>
+        /// <para></para>
+        /// </typeparam>
+        /// <param name="links">
+        /// <para>The links storage to create the link in.</para>
+        /// <para></para>
+        /// </param>
+        /// <param name="substitution">
+        /// <para>The content for the new link.</para>
+        /// <para></para>
+        /// </param>
+        /// <returns>
+        /// <para>The address of the created link.</para>
+        /// <para></para>
+        /// </returns>
         public static TLinkAddress Create<TLinkAddress>(this ILinks<TLinkAddress, LinksConstants<TLinkAddress>> links, IList<TLinkAddress>? substitution) where TLinkAddress : IUnsignedNumber<TLinkAddress>
         {
             var constants = links.Constants;
@@ -28,6 +68,32 @@ public static TLinkAddress Create<TLinkAddress>(this ILinks<TLinkAddress, LinksC
             return setter.Result;
         }
 
+        /// <summary>
+        /// <para>
+        /// Updates links that match the specified restriction with new content.
+        /// </para>
+        /// <para></para>
+        /// </summary>
+        /// <typeparam name="TLinkAddress">
+        /// <para>The type used to represent link addresses.</para>
+        /// <para></para>
+        /// </typeparam>
+        /// <param name="links">
+        /// <para>The links storage to update links in.</para>
+        /// <para></para>
+        /// </param>
+        /// <param name="restriction">
+        /// <para>The restriction criteria for selecting links to update.</para>
+        /// <para></para>
+        /// </param>
+        /// <param name="substitution">
+        /// <para>The new content for the matching links.</para>
+        /// <para></para>
+        /// </param>
+        /// <returns>
+        /// <para>The address of the updated link.</para>
+        /// <para></para>
+        /// </returns>
         public static TLinkAddress Update<TLinkAddress>(this ILinks<TLinkAddress, LinksConstants<TLinkAddress>> links, IList<TLinkAddress>? restriction, IList<TLinkAddress>? substitution) where TLinkAddress : IUnsignedNumber<TLinkAddress>
         {
             var constants = links.Constants;
@@ -36,8 +102,52 @@ public static TLinkAddress Update<TLinkAddress>(this ILinks<TLinkAddress, LinksC
             return setter.Result;
         }
 
+        /// <summary>
+        /// <para>
+        /// Deletes the specified link from the storage.
+        /// </para>
+        /// <para></para>
+        /// </summary>
+        /// <typeparam name="TLinkAddress">
+        /// <para>The type used to represent link addresses.</para>
+        /// <para></para>
+        /// </typeparam>
+        /// <param name="links">
+        /// <para>The links storage to delete the link from.</para>
+        /// <para></para>
+        /// </param>
+        /// <param name="linkToDelete">
+        /// <para>The address of the link to delete.</para>
+        /// <para></para>
+        /// </param>
+        /// <returns>
+        /// <para>The result of the delete operation.</para>
+        /// <para></para>
+        /// </returns>
         public static TLinkAddress Delete<TLinkAddress>(this ILinks<TLinkAddress, LinksConstants<TLinkAddress>> links, TLinkAddress linkToDelete) where TLinkAddress : IUnsignedNumber<TLinkAddress> => Delete(links, (IList<TLinkAddress>?)new LinkAddress<TLinkAddress>(linkToDelete));
 
+        /// <summary>
+        /// <para>
+        /// Deletes links that match the specified restriction criteria.
+        /// </para>
+        /// <para></para>
+        /// </summary>
+        /// <typeparam name="TLinkAddress">
+        /// <para>The type used to represent link addresses.</para>
+        /// <para></para>
+        /// </typeparam>
+        /// <param name="links">
+        /// <para>The links storage to delete links from.</para>
+        /// <para></para>
+        /// </param>
+        /// <param name="restriction">
+        /// <para>The restriction criteria for selecting links to delete.</para>
+        /// <para></para>
+        /// </param>
+        /// <returns>
+        /// <para>The result of the delete operation.</para>
+        /// <para></para>
+        /// </returns>
         public static TLinkAddress Delete<TLinkAddress>(this ILinks<TLinkAddress, LinksConstants<TLinkAddress>> links, IList<TLinkAddress>? restriction) where TLinkAddress : IUnsignedNumber<TLinkAddress>
         {
             var constants = links.Constants;

csharp/Platform.Data/Universal/IUniLinks.cs

@@ -31,9 +31,37 @@ public partial interface IUniLinks<TLinkAddress>
         IList<IList<IList<TLinkAddress>?>> Trigger(IList<TLinkAddress>? condition, IList<TLinkAddress>? substitution);
     }
 
+    /// <summary>
+    /// <para>
+    /// Defines the universal links interface for step by step operations.
+    /// </para>
+    /// <para></para>
+    /// </summary>
     /// <remarks>Minimal sufficient universal Links API (for step by step operations).</remarks>
     public partial interface IUniLinks<TLinkAddress>
     {
+        /// <summary>
+        /// <para>
+        /// Triggers an operation based on pattern matching and substitution with handlers.
+        /// </para>
+        /// <para></para>
+        /// </summary>
+        /// <param name="patternOrCondition">
+        /// <para>The pattern or condition for matching links.</para>
+        /// <para></para>
+        /// </param>
+        /// <param name="matchHandler">
+        /// <para>The handler function called for each matched link.</para>
+        /// <para></para>
+        /// </param>
+        /// <param name="substitution">
+        /// <para>The substitution content to apply.</para>
+        /// <para></para>
+        /// </param>
+        /// <param name="substitutionHandler">
+        /// <para>The handler function called for each substitution operation.</para>
+        /// <para></para>
+        /// </param>
         /// <returns>
         /// TLinkAddress that represents True (was finished fully) or TLinkAddress that represents False (was stopped).
         /// This is done to assure ability to push up stop signal through recursion stack.
@@ -76,9 +104,29 @@ TLinkAddress Trigger(IList<TLinkAddress>? restriction, WriteHandler<TLinkAddress
               IList<TLinkAddress>? substitution, WriteHandler<TLinkAddress>? substitutedHandler);
     }
 
+    /// <summary>
+    /// <para>
+    /// Defines the universal links interface extended with optimization methods.
+    /// </para>
+    /// <para></para>
+    /// </summary>
     /// <remarks>Extended with small optimization.</remarks>
     public partial interface IUniLinks<TLinkAddress>
     {
+        /// <summary>
+        /// <para>
+        /// Counts the number of links that match the specified restrictions.
+        /// </para>
+        /// <para></para>
+        /// </summary>
+        /// <param name="restrictions">
+        /// <para>The restrictions to apply when counting links.</para>
+        /// <para></para>
+        /// </param>
+        /// <returns>
+        /// <para>The count of links matching the restrictions.</para>
+        /// <para></para>
+        /// </returns>
         /// <remarks>
         /// Something simple should be simple and optimized.
         /// </remarks>

csharp/Platform.Data/Universal/IUniLinksCRUD.cs

@@ -93,6 +93,10 @@ public interface IUniLinksCRUD<TLinkAddress>
         /// <para>The parts.</para>
         /// <para></para>
         /// </param>
+        /// <returns>
+        /// <para>The result of the delete operation.</para>
+        /// <para></para>
+        /// </returns>
         TLinkAddress Delete(IList<TLinkAddress>? parts);
     }
 }

csharp/Platform.Data/Universal/IUniLinksIO.cs

@@ -12,6 +12,24 @@ namespace Platform.Data.Universal
     /// </remarks>
     public interface IUniLinksIO<TLinkAddress>
     {
+        /// <summary>
+        /// <para>
+        /// Outputs links that match the specified pattern using the provided handler.
+        /// </para>
+        /// <para></para>
+        /// </summary>
+        /// <param name="handler">
+        /// <para>The handler function to process each matching link.</para>
+        /// <para></para>
+        /// </param>
+        /// <param name="pattern">
+        /// <para>The pattern to match against links.</para>
+        /// <para></para>
+        /// </param>
+        /// <returns>
+        /// <para>True if all links were processed successfully, false if stopped by handler.</para>
+        /// <para></para>
+        /// </returns>
         /// <remarks>
         /// default(TLinkAddress) means any link.
         /// Single element pattern means just element (link).
@@ -31,6 +49,24 @@ public interface IUniLinksIO<TLinkAddress>
         /// </remarks>
         bool Out(Func<IList<TLinkAddress>?, bool> handler, IList<TLinkAddress>? pattern);
 
+        /// <summary>
+        /// <para>
+        /// Performs an input operation to create, update, or delete links based on before/after states.
+        /// </para>
+        /// <para></para>
+        /// </summary>
+        /// <param name="before">
+        /// <para>The state of the link before the operation.</para>
+        /// <para></para>
+        /// </param>
+        /// <param name="after">
+        /// <para>The state of the link after the operation.</para>
+        /// <para></para>
+        /// </param>
+        /// <returns>
+        /// <para>The result of the input operation.</para>
+        /// <para></para>
+        /// </returns>
         /// <remarks>
         /// default(TLinkAddress) means itself.
         /// Equivalent to:

csharp/Platform.Data/Universal/IUniLinksIOWithExtensions.cs

@@ -8,6 +8,24 @@ namespace Platform.Data.Universal
     /// <remarks>Contains some optimizations of Out.</remarks>
     public interface IUniLinksIOWithExtensions<TLinkAddress> : IUniLinksIO<TLinkAddress>
     {
+        /// <summary>
+        /// <para>
+        /// Outputs a specific part of a link matching the pattern.
+        /// </para>
+        /// <para></para>
+        /// </summary>
+        /// <param name="partType">
+        /// <para>The type of part to retrieve (0=index, 1=source, 2=target, etc.).</para>
+        /// <para></para>
+        /// </param>
+        /// <param name="pattern">
+        /// <para>The pattern to match against links.</para>
+        /// <para></para>
+        /// </param>
+        /// <returns>
+        /// <para>The specified part of the matching link, or default value if not found.</para>
+        /// <para></para>
+        /// </returns>
         /// <remarks>
         /// default(TLinkAddress) means nothing or null.
         /// Single element pattern means just element (link).
@@ -22,9 +40,37 @@ public interface IUniLinksIOWithExtensions<TLinkAddress> : IUniLinksIO<TLinkAddr
         /// </remarks>
         TLinkAddress OutOne(int partType, IList<TLinkAddress>? pattern);
 
+        /// <summary>
+        /// <para>
+        /// Outputs all links matching the specified pattern as an array.
+        /// </para>
+        /// <para></para>
+        /// </summary>
+        /// <param name="pattern">
+        /// <para>The pattern to match against links.</para>
+        /// <para></para>
+        /// </param>
+        /// <returns>
+        /// <para>An array of all links matching the pattern.</para>
+        /// <para></para>
+        /// </returns>
         /// <remarks>OutCount() returns total links in store as array.</remarks>
         IList<IList<TLinkAddress>?> OutAll(IList<TLinkAddress>? pattern);
 
+        /// <summary>
+        /// <para>
+        /// Counts the total number of links matching the specified pattern.
+        /// </para>
+        /// <para></para>
+        /// </summary>
+        /// <param name="pattern">
+        /// <para>The pattern to match against links.</para>
+        /// <para></para>
+        /// </param>
+        /// <returns>
+        /// <para>The total count of links matching the pattern.</para>
+        /// <para></para>
+        /// </returns>
         /// <remarks>OutCount() returns total amount of links in store.</remarks>
         ulong OutCount(IList<TLinkAddress>? pattern);
     }