DocComment Updates (#322)

Author: smaillet

IgnoredWords.dic

@@ -49,6 +49,7 @@ Contributors
 crlf
 csharp
 csproj
+customizable
 de
 defacto
 dllimport

docfx/ReadMe.md

@@ -5,15 +5,15 @@
 > have great memories or are otherwise easily confused. :nerd_face:)
 
 DocFX is used to generate the documentation for this library. There is confusion on
-what the "statictoc" template means and requires. It is ***LITERALLY*** that the
-Table of Contents (TOC) is statically generated. So that the entire site is servable
-from file path. This ***DOES NOT*** mean that the default+modern template is
+what the "statictoc" template means and requires. It is ***LITERALLY*** that, the
+Table of Contents (TOC) is statically generated such that the entire site is servable
+from a file path. This ***DOES NOT*** mean that the default+modern template is
 unusable for hosted static site scenarios like 'gh-pages' in GitHub. It only means
 that the TOC support will ***require*** a hosted site to provide the contents needed
 by the generated TOC client side scripting. That's it. Don't fear the built-in
 templates (Despite the lack of decent docs explaining the details [Yeah, this
-project previously fell into those gaps and even constructed a custom template to
-deal with it... Sigh, what a waste of time... :facepalm: ])
+project previously fell into those gaps and even constructed a complete custom template
+to deal with it... Sigh, what a waste of time... :facepalm: ])
 
 ## Changes Over Time
 DocFX has obsoleted the `docfxconsole` NuGet package that was used to run docfx for

src/Interop/LlvmBindingsGenerator/LlvmBindingsGenerator.csproj

@@ -22,8 +22,9 @@
 
         <!-- Sadly, the version range syntax doesn't work for Directory.Package.props so it must be provided here-->
         <!--
-        NOTE: This isn't directly used by this project as it contains nothing consumable. However, it allows for scripts
-        to restore this and guarantee the package is available when restored.
+        NOTE: This isn't directly used by this project. However, it allows for scripts to restore this project, which
+        guarantees the package is available, so they can use the contained headers as input to the application built
+        by this project.
         -->
         <PackageReference Include="Ubiquity.NET.LibLLVM" VersionOverride="20.1.*-*" GeneratePathProperty="true" PrivateAssets="all" />
     </ItemGroup>

src/Samples/Kaleidoscope/IgnoredWords.dic

@@ -31,6 +31,7 @@ ifcont
 ifresult
 imag
 impl
+initializer
 inline
 inlined
 lexer

src/Samples/Kaleidoscope/Kaleidoscope.Grammar/AST/BinaryOperatorExpression.cs

@@ -8,15 +8,31 @@
 
 namespace Kaleidoscope.Grammar.AST
 {
+    /// <summary>Identifier for the kinds of built-in operators</summary>
     public enum BuiltInOperatorKind
     {
+        /// <summary>Default value (Invalid)</summary>
         Invalid,
+
+        /// <summary>Assignment operator</summary>
         Assign,
+
+        /// <summary>Addition operator</summary>
         Add,
+
+        /// <summary>Subtraction operator</summary>
         Subtract,
+
+        /// <summary>Multiplication operator</summary>
         Multiply,
+
+        /// <summary>Division operator</summary>
         Divide,
+
+        /// <summary>Comparison operator (less)</summary>
         Less,
+
+        /// <summary>Exponentiation operator</summary>
         Pow
     }
 
@@ -60,6 +76,10 @@ public sealed override IEnumerable<IAstNode> Children
             }
         }
 
+        /// <summary>Visitor pattern 'Accept' of a visitors that don't need a parameter</summary>
+        /// <typeparam name="TResult">Type of the result from the visitor</typeparam>
+        /// <param name="visitor">Visitor to apply for each node in this expression</param>
+        /// <returns>Result of visiting this expression</returns>
         public override TResult? Accept<TResult>( IAstVisitor<TResult> visitor )
             where TResult : default
         {
@@ -68,6 +88,12 @@ public sealed override IEnumerable<IAstNode> Children
                    : visitor.Visit( this );
         }
 
+        /// <summary>Visitor pattern 'Accept' of a visitors that need a parameter</summary>
+        /// <typeparam name="TResult">Type of the result from the visitor</typeparam>
+        /// <typeparam name="TArg">Type of the argument for the visit</typeparam>
+        /// <param name="visitor">Visitor to apply for each node in this expression</param>
+        /// <param name="arg">Argument to pass to each method of the visit</param>
+        /// <returns>Result of visiting this expression</returns>
         public override TResult? Accept<TResult, TArg>( IAstVisitor<TResult, TArg> visitor, ref readonly TArg arg )
             where TResult : default
         {

src/Samples/Kaleidoscope/Kaleidoscope.Grammar/AST/ConditionalExpression.cs

@@ -8,10 +8,20 @@
 
 namespace Kaleidoscope.Grammar.AST
 {
+    /// <summary>AST node for a conditional expression</summary>
+    /// <remarks>
+    /// A conditional expression is the language equivalent of a conditional operator in most "C" like languages (ternary operator).
+    /// </remarks>
     public sealed class ConditionalExpression
         : AstNode
         , IExpression
     {
+        /// <summary>Initializes a new instance of the <see cref="ConditionalExpression"/> class.</summary>
+        /// <param name="location">Location of the expression in the source input</param>
+        /// <param name="condition">Expression for the condition</param>
+        /// <param name="thenExpression">Expression for the `then` clause of the conditional expression</param>
+        /// <param name="elseExpression">Expression for the `else` clause of the conditional expression</param>
+        /// <param name="resultVar"><see cref="LocalVariableDeclaration"/> to represent the results of the expression</param>
         public ConditionalExpression( SourceRange location
                                     , IExpression condition
                                     , IExpression thenExpression
@@ -26,19 +36,26 @@ public ConditionalExpression( SourceRange location
             ResultVariable = resultVar;
         }
 
+        /// <summary>Gets the expression for the condition</summary>
         public IExpression Condition { get; }
 
+        /// <summary>Gets the expression for the `then` clause</summary>
         public IExpression ThenExpression { get; }
 
+        /// <summary>Gets the expression for the `else` clause</summary>
         public IExpression ElseExpression { get; }
 
-        // Compiler generated result variable supports building conditional
-        // expressions without the need for SSA form in the AST/Code generation
-        // by using mutable variables. The result is assigned a value from both
-        // sides of the branch. In pure SSA form this isn't needed as a PHI node
-        // would be used instead.
+        /// <summary>Gets the result of the expression as a <see cref="LocalVariableDeclaration"/></summary>
+        /// <remarks>
+        /// Compiler generated result variable supports building conditional
+        /// expressions without the need for SSA form in the AST/Code generation
+        /// by using mutable variables. The result is assigned a value from both
+        /// sides of the branch. In pure SSA form this isn't needed as a PHI node
+        /// would be used instead.
+        /// </remarks>
         public LocalVariableDeclaration ResultVariable { get; }
 
+        /// <inheritdoc cref="BinaryOperatorExpression.Accept{TResult}(IAstVisitor{TResult})"/>
         public override TResult? Accept<TResult>( IAstVisitor<TResult> visitor )
             where TResult : default
         {
@@ -47,6 +64,7 @@ public ConditionalExpression( SourceRange location
                    : visitor.Visit( this );
         }
 
+        /// <inheritdoc cref="BinaryOperatorExpression.Accept{TResult, TArg}(IAstVisitor{TResult, TArg}, ref readonly TArg)"/>
         public override TResult? Accept<TResult, TArg>( IAstVisitor<TResult, TArg> visitor, ref readonly TArg arg )
             where TResult : default
         {
@@ -55,6 +73,7 @@ public ConditionalExpression( SourceRange location
                    : visitor.Visit( this, in arg );
         }
 
+        /// <inheritdoc/>
         public override IEnumerable<IAstNode> Children
         {
             get
@@ -65,6 +84,7 @@ public override IEnumerable<IAstNode> Children
             }
         }
 
+        /// <inheritdoc/>
         public override string ToString( )
         {
             return $"Conditional({Condition}, {ThenExpression}, {ElseExpression})";

src/Samples/Kaleidoscope/Kaleidoscope.Grammar/AST/ConstantExpression.cs

@@ -9,18 +9,24 @@
 
 namespace Kaleidoscope.Grammar.AST
 {
+    /// <summary>Kaleidoscope AST node for a constant</summary>
     public sealed class ConstantExpression
         : AstNode
         , IExpression
     {
+        /// <summary>Initializes a new instance of the <see cref="ConstantExpression"/> class.</summary>
+        /// <param name="location">Location of the expression in the original source</param>
+        /// <param name="value">Value of the constant</param>
         public ConstantExpression( SourceRange location, double value )
             : base( location )
         {
             Value = value;
         }
 
+        /// <summary>Gets the value of this constant expression</summary>
         public double Value { get; }
 
+        /// <inheritdoc cref="BinaryOperatorExpression.Accept{TResult}(IAstVisitor{TResult})"/>
         public override TResult? Accept<TResult>( IAstVisitor<TResult> visitor )
             where TResult : default
         {
@@ -29,6 +35,7 @@ public ConstantExpression( SourceRange location, double value )
                    : visitor.Visit( this );
         }
 
+        /// <inheritdoc cref="BinaryOperatorExpression.Accept{TResult, TArg}(IAstVisitor{TResult, TArg}, ref readonly TArg)"/>
         public override TResult? Accept<TResult, TArg>( IAstVisitor<TResult, TArg> visitor, ref readonly TArg arg )
             where TResult : default
         {
@@ -37,8 +44,10 @@ public ConstantExpression( SourceRange location, double value )
                    : visitor.Visit( this, in arg );
         }
 
+        /// <inheritdoc/>
         public override IEnumerable<IAstNode> Children => [];
 
+        /// <inheritdoc/>
         public override string ToString( )
         {
             return Value.ToString( CultureInfo.CurrentCulture );

src/Samples/Kaleidoscope/Kaleidoscope.Grammar/AST/DiagnosticCode.cs

@@ -3,24 +3,44 @@
 
 namespace Kaleidoscope.Grammar.AST
 {
+    /// <summary>Symbolic names for code values reported in diagnostic messages</summary>
     public enum DiagnosticCode
         : int
     {
+        /// <summary>No code value</summary>
         None = 0,
 
         // Codes with integer values < 1000 are reserved for grammar states
 
         // AST Builder
+
+        /// <summary>Syntax error, input is not parsable</summary>
         SyntaxError = 1000,
+
+        /// <summary>Syntax indicates a variable but that symbol's name is unknown</summary>
         UnknownVariable,
+
+        /// <summary>Syntax indicates an invocation of a function but that function's name is unknown</summary>
         InvokeUnknownFunction,
+
+        /// <summary>Unary op expression is invalid</summary>
         InvalidUnaryOp,
+
+        /// <summary>Invalid reference to an operator</summary>
         InvalidUnaryOpRef,
+
+        /// <summary>Binary op expression is invalid</summary>
         InvalidBinaryOp,
+
+        /// <summary>Specified unary operator was not found</summary>
         UnaryOpNotFound,
+
+        /// <summary>Re-declaration is incompatible with the original</summary>
         IncompatibleRedclaration,
 
         // Post parse
+
+        /// <summary>Parse was cancelled</summary>
         ParseCanceled = 2000,
     }
 }

src/Samples/Kaleidoscope/Kaleidoscope.Grammar/AST/ForInExpression.cs

@@ -8,10 +8,17 @@
 
 namespace Kaleidoscope.Grammar.AST
 {
+    /// <summary>Kaleidoscope AST node for a <c>ForIn</c> expression</summary>
     public sealed class ForInExpression
         : AstNode
         , IExpression
     {
+        /// <summary>Initializes a new instance of the <see cref="ForInExpression"/> class.</summary>
+        /// <param name="location">Location of the expression in the source input</param>
+        /// <param name="loopVariable">Declaration of the variable to use for the loop</param>
+        /// <param name="condition">Exit Condition for the loop</param>
+        /// <param name="step">Step value to increment <paramref name="loopVariable"/> by with each iteration of the loop</param>
+        /// <param name="body">The body of the loop to invoke on each iteration</param>
         public ForInExpression( SourceRange location
                               , LocalVariableDeclaration loopVariable
                               , IExpression condition
@@ -26,14 +33,19 @@ public ForInExpression( SourceRange location
             Body = body;
         }
 
+        /// <summary>Gets the declaration of the variable to use for the loop</summary>
         public LocalVariableDeclaration LoopVariable { get; }
 
+        /// <summary>Gets the exit Condition for the loop</summary>
         public IExpression Condition { get; }
 
+        /// <summary>Gets the step value to increment <see cref="LoopVariable"/> by with each iteration of the loop</summary>
         public IExpression Step { get; }
 
+        /// <summary>Gets the body of the loop to invoke on each iteration</summary>
         public IExpression Body { get; }
 
+        /// <inheritdoc cref="BinaryOperatorExpression.Accept{TResult}(IAstVisitor{TResult})"/>
         public override TResult? Accept<TResult>( IAstVisitor<TResult> visitor )
             where TResult : default
         {
@@ -42,6 +54,7 @@ public ForInExpression( SourceRange location
                    : visitor.Visit( this );
         }
 
+        /// <inheritdoc cref="BinaryOperatorExpression.Accept{TResult, TArg}(IAstVisitor{TResult, TArg}, ref readonly TArg)"/>
         public override TResult? Accept<TResult, TArg>( IAstVisitor<TResult, TArg> visitor, ref readonly TArg arg )
             where TResult : default
         {
@@ -50,6 +63,7 @@ public ForInExpression( SourceRange location
                    : visitor.Visit( this, in arg );
         }
 
+        /// <inheritdoc/>
         public override IEnumerable<IAstNode> Children
         {
             get
@@ -61,6 +75,7 @@ public override IEnumerable<IAstNode> Children
             }
         }
 
+        /// <inheritdoc/>
         public override string ToString( )
         {
             return $"for({LoopVariable}, {Condition}, {Step}, {Body})";

src/Samples/Kaleidoscope/Kaleidoscope.Grammar/AST/FunctionCallExpression.cs

@@ -9,21 +9,29 @@
 
 namespace Kaleidoscope.Grammar.AST
 {
+    /// <summary>Kaleidoscope AST Node for a function call expression</summary>
     public sealed class FunctionCallExpression
         : AstNode
         , IExpression
     {
+        /// <summary>Initializes a new instance of the <see cref="FunctionCallExpression"/> class.</summary>
+        /// <param name="location">Location of the node in the source input</param>
+        /// <param name="functionPrototype">Prototype of the function to call</param>
+        /// <param name="args">Arguments to provide to the function</param>
         public FunctionCallExpression( SourceRange location, Prototype functionPrototype, params IEnumerable<IExpression> args )
             : base( location )
         {
             FunctionPrototype = functionPrototype;
             Arguments = [ .. args ];
         }
 
+        /// <summary>Gets the prototype of the function to call</summary>
         public Prototype FunctionPrototype { get; }
 
+        /// <summary>Gets the arguments to provide to the function</summary>
         public IReadOnlyList<IExpression> Arguments { get; }
 
+        /// <inheritdoc/>
         public override IEnumerable<IAstNode> Children
         {
             get
@@ -32,6 +40,7 @@ public override IEnumerable<IAstNode> Children
             }
         }
 
+        /// <inheritdoc cref="BinaryOperatorExpression.Accept{TResult}(IAstVisitor{TResult})"/>
         public override TResult? Accept<TResult>( IAstVisitor<TResult> visitor )
             where TResult : default
         {
@@ -40,6 +49,7 @@ public override IEnumerable<IAstNode> Children
                    : visitor.Visit( this );
         }
 
+        /// <inheritdoc cref="BinaryOperatorExpression.Accept{TResult, TArg}(IAstVisitor{TResult, TArg}, ref readonly TArg)"/>
         public override TResult? Accept<TResult, TArg>( IAstVisitor<TResult, TArg> visitor, ref readonly TArg arg )
             where TResult : default
         {
@@ -48,6 +58,7 @@ public override IEnumerable<IAstNode> Children
                    : visitor.Visit( this, in arg );
         }
 
+        /// <inheritdoc/>
         public override string ToString( )
         {
             return Arguments.Count == 0