Add comprehensive XML documentation for IDE IntelliSense support (#42)

* Complete XML documentation for all public APIs

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: eNeRGy164 <10671831+eNeRGy164@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: 3 people

src/DendroDocs.Shared/DendroDocs.Shared.csproj

@@ -2,10 +2,11 @@
 
   <PropertyGroup>
     <IsPackable>true</IsPackable>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
 
     <Authors>Michaël Hompus</Authors>
     <PackageProjectUrl>https://github.com/DendroDocs/dotnet-shared-lib</PackageProjectUrl>
-    <Description></Description>
+    <Description>Shared library for the DendroDocs ecosystem providing common utilities, data models, and extensions for .NET code analysis and documentation generation.</Description>
     <Copyright>Copyright Michaël Hompus 2019</Copyright>
     <RepositoryUrl>https://github.com/DendroDocs/dotnet-shared-lib</RepositoryUrl>
     <RepositoryType>git</RepositoryType>

src/DendroDocs.Shared/Descriptions/ArgumentDescription.cs

@@ -1,9 +1,18 @@
 namespace DendroDocs;
 
+/// <summary>
+/// Represents an argument passed to a method or constructor with its type and text representation.
+/// </summary>
 [DebuggerDisplay("Argument {Text} ({Type,nq})")]
 public class ArgumentDescription(string type, string text)
 {
+    /// <summary>
+    /// Gets the type of the argument.
+    /// </summary>
     public string Type { get; } = type ?? throw new ArgumentNullException(nameof(type));
 
+    /// <summary>
+    /// Gets the text representation of the argument value.
+    /// </summary>
     public string Text { get; } = text ?? throw new ArgumentNullException(nameof(text));
 }

src/DendroDocs.Shared/Descriptions/AssignmentDescription.cs

@@ -1,11 +1,23 @@
 namespace DendroDocs;
 
+/// <summary>
+/// Represents an assignment statement with left-hand side, operator, and right-hand side expressions.
+/// </summary>
 [DebuggerDisplay("Assignment \"{Left,nq} {Operator,nq} {Right,nq}\"")]
 public class AssignmentDescription(string left, string @operator, string right) : Statement
 {
+    /// <summary>
+    /// Gets the left-hand side expression of the assignment.
+    /// </summary>
     public string Left { get; } = left ?? throw new ArgumentNullException(nameof(left));
 
+    /// <summary>
+    /// Gets the assignment operator (e.g., "=", "+=", "-=").
+    /// </summary>
     public string Operator { get; } = @operator ?? throw new ArgumentNullException(nameof(@operator));
 
+    /// <summary>
+    /// Gets the right-hand side expression of the assignment.
+    /// </summary>
     public string Right { get; } = right ?? throw new ArgumentNullException(nameof(right));
 }

src/DendroDocs.Shared/Descriptions/AttributeArgumentDescription.cs

@@ -1,11 +1,23 @@
 namespace DendroDocs;
 
+/// <summary>
+/// Represents an argument passed to an attribute with its name, type, and value.
+/// </summary>
 [DebuggerDisplay("AttributeArgument {Name} {Type} {Value}")]
 public class AttributeArgumentDescription(string? name, string? type, string? value)
 {
+    /// <summary>
+    /// Gets the name of the attribute argument.
+    /// </summary>
     public string Name { get; } = name ?? throw new ArgumentNullException("name");
 
+    /// <summary>
+    /// Gets the type of the attribute argument.
+    /// </summary>
     public string Type { get; } = type ?? throw new ArgumentNullException("type");
 
+    /// <summary>
+    /// Gets the value of the attribute argument.
+    /// </summary>
     public string Value { get; } = value ?? throw new ArgumentNullException("value");
 }

src/DendroDocs.Shared/Descriptions/AttributeDescription.cs

@@ -2,13 +2,25 @@
 
 namespace DendroDocs;
 
+/// <summary>
+/// Represents an attribute applied to a type or member with its type, name, and arguments.
+/// </summary>
 [DebuggerDisplay("Attribute {Type} {Name}")]
 public class AttributeDescription(string? type, string? name)
 {
+    /// <summary>
+    /// Gets the type name of the attribute.
+    /// </summary>
     public string Type { get; } = type ?? throw new ArgumentNullException(nameof(type));
 
+    /// <summary>
+    /// Gets the name of the attribute.
+    /// </summary>
     public string Name { get; } = name ?? throw new ArgumentNullException(nameof(name));
 
+    /// <summary>
+    /// Gets the collection of arguments passed to the attribute.
+    /// </summary>
     [Newtonsoft.Json.JsonProperty(ItemTypeNameHandling = Newtonsoft.Json.TypeNameHandling.None)]
     [Newtonsoft.Json.JsonConverter(typeof(ConcreteTypeConverter<List<AttributeArgumentDescription>>))]
     public List<AttributeArgumentDescription> Arguments { get; init; } = [];

src/DendroDocs.Shared/Descriptions/ConstructorDescription.cs

@@ -2,9 +2,17 @@
 
 namespace DendroDocs;
 
+/// <summary>
+/// Represents a constructor with its parameters and method body statements.
+/// </summary>
 [DebuggerDisplay("Constructor {Name}")]
 public class ConstructorDescription(string name) : MemberDescription(name), IHaveAMethodBody, IJsonOnDeserialized
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ConstructorDescription"/> class with constructor statements.
+    /// </summary>
+    /// <param name="name">The name of the constructor.</param>
+    /// <param name="statements">The collection of statements in the constructor body.</param>
     [Newtonsoft.Json.JsonConstructor]
     [JsonConstructor]
     public ConstructorDescription(string name, List<Statement> statements)
@@ -13,21 +21,37 @@ public ConstructorDescription(string name, List<Statement> statements)
         this.Statements = statements ?? [];
     }
 
+    /// <summary>
+    /// Gets the collection of parameter descriptions for the constructor.
+    /// </summary>
     [Newtonsoft.Json.JsonProperty(ItemTypeNameHandling = Newtonsoft.Json.TypeNameHandling.None)]
     [Newtonsoft.Json.JsonConverter(typeof(ConcreteTypeConverter<List<ParameterDescription>>))]
     public List<ParameterDescription> Parameters { get; } = [];
 
+    /// <summary>
+    /// Gets the collection of statements that make up the constructor body.
+    /// </summary>
     public List<Statement> Statements { get; } = [];
 
+    /// <summary>
+    /// Gets the member type, which is always <see cref="MemberType.Constructor"/> for constructor descriptions.
+    /// </summary>
     [JsonIgnore]
     public override MemberType MemberType => MemberType.Constructor;
 
+    /// <summary>
+    /// Called after deserialization to restore parent-child relationships between statements.
+    /// </summary>
+    /// <param name="context">The streaming context for deserialization.</param>
     [OnDeserialized]
     internal void OnDeserializedMethod(StreamingContext context)
     {
         this.OnDeserialized();
     }
 
+    /// <summary>
+    /// Restores parent-child relationships between this constructor and its statements after deserialization.
+    /// </summary>
     public void OnDeserialized()
     {
         foreach (var statement in this.Statements)

src/DendroDocs.Shared/Descriptions/DocumentationComments/Attribute.cs

@@ -1,9 +1,24 @@
 namespace DendroDocs.DocumentationComments;
 
+/// <summary>
+/// Provides constant values for XML documentation comment attribute names.
+/// </summary>
 public class Attribute
 {
+    /// <summary>
+    /// The "name" attribute constant.
+    /// </summary>
     public const string Name = "name";
+    /// <summary>
+    /// The "cref" attribute constant.
+    /// </summary>
     public const string CRef = "cref";
+    /// <summary>
+    /// The "type" attribute constant.
+    /// </summary>
     public const string Type = "type";
+    /// <summary>
+    /// The "start" attribute constant.
+    /// </summary>
     public const string Start = "start";
 }

src/DendroDocs.Shared/Descriptions/DocumentationComments/Block.cs

@@ -1,8 +1,20 @@
 namespace DendroDocs.DocumentationComments;
 
+/// <summary>
+/// Provides constant values for XML documentation comment block element names.
+/// </summary>
 public class Block
 {
+    /// <summary>
+    /// The "code" block element constant.
+    /// </summary>
     public const string Code = "code";
+    /// <summary>
+    /// The "list" block element constant.
+    /// </summary>
     public const string List = "list";
+    /// <summary>
+    /// The "para" block element constant.
+    /// </summary>
     public const string Para = "para";
 }

src/DendroDocs.Shared/Descriptions/DocumentationComments/Inline.cs

@@ -1,9 +1,24 @@
 namespace DendroDocs.DocumentationComments;
 
+/// <summary>
+/// Provides constant values for XML documentation comment inline element names.
+/// </summary>
 public class Inline
 {
+    /// <summary>
+    /// The "c" inline element constant for inline code.
+    /// </summary>
     public const string C = "c";
+    /// <summary>
+    /// The "paramref" inline element constant for parameter references.
+    /// </summary>
     public const string ParamRef = "paramref";
+    /// <summary>
+    /// The "typeparamref" inline element constant for type parameter references.
+    /// </summary>
     public const string TypeParamRef = "typeparamref";
+    /// <summary>
+    /// The "see" inline element constant for cross-references.
+    /// </summary>
     public const string See = "see";
 }

src/DendroDocs.Shared/Descriptions/DocumentationComments/List.cs

@@ -1,9 +1,24 @@
 namespace DendroDocs.DocumentationComments;
 
+/// <summary>
+/// Provides constant values for XML documentation comment list element names.
+/// </summary>
 public class List
 {
+    /// <summary>
+    /// The "item" list element constant.
+    /// </summary>
     public const string Item = "item";
+    /// <summary>
+    /// The "term" list element constant.
+    /// </summary>
     public const string Term = "term";
+    /// <summary>
+    /// The "description" list element constant.
+    /// </summary>
     public const string Description = "description";
+    /// <summary>
+    /// The "listHeader" list element constant.
+    /// </summary>
     public const string ListHeader = "listHeader";
 }