Add multi-targeting TFM for Runtime.Utils (#302)

* This adds `allows ref struct`  to `IAstVisitor<TResult, TArg>` for the .NET 9+ versions that support such a thing.

Author: smaillet

IgnoredWords.dic

@@ -25,6 +25,7 @@ blittable
 blockdiag
 blog
 bool
+borked
 buildbinoutput
 buildtransitive
 builtinop

docfx/docfx.json

@@ -78,7 +78,15 @@
                     "files": ["**.csproj"]
                 }
             ],
-            "dest": "runtime-utils/api"
+            "dest": "runtime-utils/api",
+            "properties": {
+                // use .NET 8.0 for the TFM as it is multi-targeting
+                // Sadly, DocFX can't find the dependent project builds if this is .NET 9.0
+                // and then generates warnings as a result. (DocFX metadata generation is
+                // pretty well borked and needs replacement as there are a LOT of workarounds
+                // in this project let alone all the ones found on-line.)
+                "TargetFramework": "net8.0"
+            }
         },
         {
             // TextUX  library
@@ -90,10 +98,7 @@
                     "files": ["**.csproj"]
                 }
             ],
-            "dest": "TextUX/api",
-            "properties": {
-                "DefineConstants": "DOCFX_BUILD"
-            }
+            "dest": "TextUX/api"
         }
     ],
     "build": {

src/Ubiquity.NET.Runtime.Utils/IAstVisitor.cs

@@ -21,8 +21,9 @@ public interface IAstVisitor<out TResult>
     /// <remarks>
     /// <para>This interface is used for visiting an AST, typically for generating code but may also
     /// be used to detect errors in the AST etc..</para>
-    /// <para>The <typeparamref name="TArg"/> is typically used for a Byref-like type where the type
-    /// may NOT be stored on the heap and MUST be passed via `ref readonly`.</para>
+    /// <para>In frameworks that support it the <typeparamref name="TArg"/> is typically used for a <c>byref-like</c>
+    /// type where the type may NOT be stored on the heap and MUST be passed via <c>ref readonly</c>. (Such support
+    /// requires at least .NET 9 to support <c>allows ref struct</c>, which requires runtime support.)</para>
     /// </remarks>
     public interface IAstVisitor<out TResult, TArg>
 #if NET9_0_OR_GREATER

src/Ubiquity.NET.Runtime.Utils/IParser.cs

@@ -3,18 +3,21 @@
 
 using System.IO;
 
+// CONSIDER: Adaptation that accepts IParsesErrorReporter as a param argument to the parse APIs instead of relying on
+//           an implementation to "hold" one.
+
 namespace Ubiquity.NET.Runtime.Utils
 {
-    /// <summary>Core interface for a general parser</summary>
+    /// <summary>Core interface for a general parser that parses input text into an AST represented as a root <see cref="IAstNode"/></summary>
     public interface IParser
     {
         /// <summary>Try parsing the given input text</summary>
         /// <param name="txt">Text to parse</param>
         /// <returns>Parse results as an <see cref="IAstNode"/></returns>
         /// <remarks>
-        /// If the parse fails then the result is <see langword="false"/>.
+        /// If the parse fails then the result is <see langword="null"/>.
         /// Errors from the parse are reported through error listeners provided
-        /// to the parser. Normally this is done via the constructor of a type
+        /// to the parser. Normally, this is done via the constructor of a type
         /// implementing this interface.
         /// </remarks>
         IAstNode? Parse( string txt );

src/Ubiquity.NET.Runtime.Utils/Ubiquity.NET.Runtime.Utils.csproj

@@ -1,6 +1,6 @@
 <Project Sdk="Microsoft.NET.Sdk">
     <PropertyGroup>
-        <TargetFramework>net8.0</TargetFramework>
+        <TargetFrameworks>net8.0;net9.0</TargetFrameworks>
         <LangVersion>13</LangVersion>
         <Nullable>enable</Nullable>
         <!--Until C#14 and the "field" and "extension" keywords are available use the preview language -->