UbiquityDotNET · smaillet · Nov 6, 2025 · Nov 6, 2025
diff --git a/Build-Docs.ps1 b/Build-Docs.ps1
@@ -27,7 +27,7 @@ Param(
     [switch]$ShowDocs
 )
 
-$docFXToolVersion = '2.78.3'
+$docFXToolVersion = '2.78.4'
 
 $InformationPreference = 'Continue'
 $ErrorInformationPreference = 'Stop'

diff --git a/Build-Source.ps1 b/Build-Source.ps1
@@ -31,7 +31,7 @@ try
     $buildInfo = Initialize-BuildEnvironment -FullInit:$FullInit
 
     # build the Managed code support
-    Write-Information "dotnet build 'src\Ubiquity.NET.Llvm.slnx' -c $Configuration"
+    Write-Information "dotnet build --tl:off 'src\Ubiquity.NET.Llvm.slnx' -c $Configuration"
     Invoke-External dotnet build --tl:off 'src\Ubiquity.NET.Llvm.slnx' '-c' $Configuration
 }
 catch

diff --git a/Directory.Build.targets b/Directory.Build.targets
@@ -10,6 +10,7 @@
     will ensure the folder exists during restore so that it won't fail.
     -->
     <Target Name="EnsureBuildOutputPaths" Condition="!Exists($(PackageOutputPath))">
+        <Message Importance="high" Text="PackageOutputPath: $(PackageOutputPath)"/>
         <MakeDir Directories="$(PackageOutputPath)"/>
     </Target>
 
@@ -26,6 +27,7 @@
         <Message Importance="normal" Text="                  Platform: $(Platform)"/>
         <Message Importance="normal" Text="             Configuration: $(Configuration)"/>
         <Message Importance="normal" Text="         NETCoreSdkVersion: $(NETCoreSdkVersion)"/>
+        <Message Importance="normal" Text="           TargetFramework: $(TargetFramework)"/>
     </Target>
 
     <Target Name="VerifyProjectSettings" Condition="'$(MSBuildProjectExtension)'=='.csproj'">

diff --git a/Directory.Packages.props b/Directory.Packages.props
@@ -1,55 +1,57 @@
 <?xml version="1.0" encoding="utf-8"?>
 <Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
-    <!--
+  <!--
     Global references are included in ALL projects in this repository
-    -->
-    <ItemGroup>
-        <GlobalPackageReference Include="Ubiquity.NET.Versioning.Build.Tasks" Version="5.0.7-alpha.0.1" />
-        <GlobalPackageReference Include="IDisposableAnalyzers" Version="4.0.8" Condition="'$(NoCommonAnalyzers)' !=' true'" />
-        <GlobalPackageReference Include="MustUseRetVal" Version="0.0.2" Condition="'$(NoCommonAnalyzers)' !=' true'" />
-        <!--
+  -->
+  <ItemGroup>
+    <GlobalPackageReference Include="Ubiquity.NET.Versioning.Build.Tasks" Version="5.0.7" />
+    <GlobalPackageReference Include="IDisposableAnalyzers" Version="4.0.8" Condition="'$(NoCommonAnalyzers)' !=' true'" />
+    <GlobalPackageReference Include="MustUseRetVal" Version="0.0.2" Condition="'$(NoCommonAnalyzers)' !=' true'" />
+    <!--
         NOTE: This analyzer is sadly, perpetually in "pre-release mode". There have been many issues/discussion on the point
         and it has all fallen on deaf ears. So policies regarding "NO-Prerelease" components need to be overruled on this one
         -->
-        <GlobalPackageReference Include="StyleCop.Analyzers" Version="1.2.0-beta.556" Condition="'$(UseStyleCop)' != 'false'" />
-    </ItemGroup>
-    <!--
+    <GlobalPackageReference Include="StyleCop.Analyzers" Version="1.2.0-beta.556" Condition="'$(UseStyleCop)' != 'false'" />
+  </ItemGroup>
+
+  <!--
     Package versions made consistent across all packages referenced in this repository
-    -->
-    <ItemGroup>
-        <!-- Roslyn Analyzers ***MUST*** target older framework -->
-        <PackageVersion Include="AnsiCodes" Version="0.2.1" />
-        <PackageVersion Include="Microsoft.CodeAnalysis" Version="4.14.0" />
-        <PackageVersion Include="Microsoft.CodeAnalysis.Analyzers" Version="4.14.0" />
-        <PackageVersion Include="Microsoft.CodeAnalysis.CSharp" Version="4.14.0" />
-        <PackageVersion Include="Microsoft.CodeAnalysis.CSharp.Features" Version="4.14.0" />
-        <PackageVersion Include="Microsoft.CodeAnalysis.VisualBasic.Features" Version="4.14.0" />
-        <PackageVersion Include="Basic.Reference.Assemblies.Net80" Version="1.8.3" />
-        <PackageVersion Include="System.Buffers" Version="4.6.1" />
-        <PackageVersion Include="System.Collections.Immutable" Version="9.0.8" />
-        <PackageVersion Include="System.CommandLine" Version="2.0.0-rc.2.25502.107" />
+  -->
+  <ItemGroup>
+    <!-- Roslyn Analyzers ***MUST*** target older framework -->
+    <PackageVersion Include="AnsiCodes" Version="0.2.1" />
+    <PackageVersion Include="Microsoft.CodeAnalysis" Version="4.14.0" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.Analyzers" Version="4.14.0" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.CSharp" Version="4.14.0" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.CSharp.Features" Version="4.14.0" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.VisualBasic.Features" Version="4.14.0" />
+    <PackageVersion Include="Basic.Reference.Assemblies.Net80" Version="1.8.3" />
+    <PackageVersion Include="PolySharp" Version="1.15.0" />
+    <PackageVersion Include="System.Buffers" Version="4.6.1" />
+    <PackageVersion Include="System.Collections.Immutable" Version="9.0.10" />
+    <PackageVersion Include="System.CommandLine" Version="2.0.0-rc.2.25502.107" />
 
-        <!-- Security vulnerability overrides -->
-        <!-- Workaround(2): https://github.com/dotnet/roslyn-sdk/issues/1191 -->
-        <PackageVersion Include="System.Formats.Asn1" Version="9.0.10" />
+    <!-- Security vulnerability overrides -->
+    <!-- Workaround(2): https://github.com/dotnet/roslyn-sdk/issues/1191 -->
+    <PackageVersion Include="System.Formats.Asn1" Version="9.0.10" />
 
-        <!-- Common packages for solution -->
-        <PackageVersion Include="System.Linq.Async" Version="6.0.3" />
-        <PackageVersion Include="Ubiquity.NET.LibLLVM" Version="20.1.8" />
-        <PackageVersion Include="Ubiquity.NET.Versioning" Version="6.0.2-beta" />
-        <PackageVersion Include="Antlr4BuildTasks" Version="12.11.0" />
-        <PackageVersion Include="Antlr4.Runtime.Standard" Version="4.13.1" />
-        <PackageVersion Include="OpenSoftware.DgmlBuilder" Version="2.1.0" />
-        <PackageVersion Include="CppSharp" Version="1.1.5.3168" />
-        <PackageVersion Include="System.CodeDom" Version="9.0.7" />
+    <!-- Common packages for solution -->
+    <PackageVersion Include="System.Linq.Async" Version="6.0.3" />
+    <PackageVersion Include="Ubiquity.NET.LibLLVM" Version="20.1.8" />
+    <PackageVersion Include="Ubiquity.NET.Versioning" Version="6.0.2-beta" />
+    <PackageVersion Include="Antlr4BuildTasks" Version="12.11.0" />
+    <PackageVersion Include="Antlr4.Runtime.Standard" Version="4.13.1" />
+    <PackageVersion Include="OpenSoftware.DgmlBuilder" Version="2.1.0" />
+    <PackageVersion Include="CppSharp" Version="1.1.5.3168" />
+    <PackageVersion Include="System.CodeDom" Version="9.0.7" />
 
-        <!-- Tests all use the same framework versions -->
-        <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="18.0.0" />
-        <PackageVersion Include="MSTest.TestAdapter" Version="4.0.1" />
-        <PackageVersion Include="MSTest.TestFramework" Version="4.0.1" />
-        <PackageVersion Include="Tmds.ExecFunction" Version="0.8.0" />
-        <PackageVersion Include="Microsoft.CodeAnalysis.CSharp.Analyzer.Testing" Version="1.1.2" />
-        <PackageVersion Include="Microsoft.CodeAnalysis.CSharp.CodeFix.Testing" Version="1.1.2" />
-        <PackageVersion Include="Microsoft.CodeAnalysis.CSharp.CodeRefactoring.Testing" Version="1.1.2" />
-    </ItemGroup>
+    <!-- Tests all use the same framework versions -->
+    <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="18.0.0" />
+    <PackageVersion Include="MSTest.TestAdapter" Version="4.0.1" />
+    <PackageVersion Include="MSTest.TestFramework" Version="4.0.1" />
+    <PackageVersion Include="Tmds.ExecFunction" Version="0.8.0" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.CSharp.Analyzer.Testing" Version="1.1.2" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.CSharp.CodeFix.Testing" Version="1.1.2" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.CSharp.CodeRefactoring.Testing" Version="1.1.2" />
+  </ItemGroup>
 </Project>
diff --git a/OneFlow/ReadMe.md b/OneFlow/ReadMe.md
@@ -4,5 +4,5 @@ This repository follows the [OneFlow](https://www.endoflineblog.com/oneflow-a-gi
 model and work-flow. With one active long term branch 'develop'. The master branch is
 present and long term but is not active, it only points to the latest official release
 (including preview releases) of the project. This is a convenience to allow getting the
-latests released source quickly. Generally the scripts used here are only for release
-managers and are not required (or even an option) for most contributors.
+latest released source quickly. Generally speaking, the scripts used here are only for
+release managers and are not required (or even an option) for most contributors.
diff --git a/Show-Docs.ps1 b/Show-Docs.ps1
@@ -18,7 +18,7 @@ Param(
     [string]$DocsPathToHost
 )
 
-$docFXToolVersion = '2.78.3'
+$docFXToolVersion = '2.78.4'
 
 $InformationPreference = 'Continue'
 $ErrorInformationPreference = 'Stop'

diff --git a/docfx/CommandLine/toc.yml b/docfx/CommandLine/toc.yml
@@ -1,4 +1,4 @@
-# TOC (Left nav) for the 'extensions' folder
+# TOC (Left nav) for the 'CommandLine' folder
 - name: Overview
   href: index.md
 - name: Namespaces

diff --git a/docfx/ReadMe.md b/docfx/ReadMe.md
@@ -10,19 +10,19 @@ DocFX is used to generate the documentation for this library. There is confusion
 ***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
+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 complete custom template to deal with it... Sigh, what a waste of time...
-:facepalm: ])
+:facepalm: ]
 
 ## Changes Over Time
 DocFX has obsoleted the `docfxconsole` NuGet package that was used to run docfx for a
 project via MSBUILD. Instead it focused on a .NET tool to do it all via the command line.
-Ultimately the docfx.json serves as the "project" file for the different site builds.
-The PowerShell script `Build-Docs.ps1` was updated to use the new tool directly. Using that
-script should have little or no impact on the overall flow. There is a "no-targets" project
-in the solution to enable easier access to the input files but does not itself, generate any
-docs - it's just a placeholder.
+Ultimately the docfx.json serves as the corellary to a "project" file for the different site
+builds. The PowerShell script `Build-Docs.ps1` was updated to use the new tool directly.
+Using that script should have little or no impact on the overall flow. There is a
+"no-targets" project in the solution to enable easier access to the input files but does not
+itself, generate any docs - it's just a placeholder.
 
 ## Files used by the docs generation
 There are a lot of files used to generate the docs and the concept of a Table of Contents
@@ -77,3 +77,76 @@ Since this is generated it is listed in the [.gitignore](#gitignore) file.
 #### Library Content
 These folders (named after the `*` portion of the [api-*](#api-*) folder names contains
 manually written additional files, articles, samples etc... related to a given library.
+
+## Guid to wrting XML DOC comments
+When dealing with doc comments the XML can get in the way of general readability of the
+source code. There is an inherent tension beween how a particular editor renders the docs
+for a symbol/method (VS calls this "Quick Info") and how it is rendered in the final
+documentation by docfx. This guides general use to simplify things as much as possible.
+
+### Lists
+The largest intrusion of the XML into the source is that of lists. The XML doc comments
+official support is to use the `<list>` tag. However, that is VERY intrusive and doesn't
+easily support sub-lists. Consider:
+
+``` C#
+/// Additional steps might include:
+/// <para>
+/// <list type="number">
+///     <item>App specific Validation/semantic analysis</item>
+///     <item>Binding of results to an app specific type</item>
+///     <item>
+///     Act on the results as proper for the application
+///     <list type="number">
+///         <item>This might include actions parsed but generally isolating the various stages is an easier to understand/maintain model</item>
+///         <item>Usually this is just app specific code that uses the bound results to adapt behavior</item>
+///     </list>
+///     </item>
+/// </list>
+/// </para>
+```
+
+versus:
+``` C#
+/// Additional steps might include:<br/>
+///
+/// 1) App specific Validation/semantic analysis<br/>
+/// 2) Binding of results to an app specific type<br/>
+/// 3) Act on the results as proper for the application<br/>
+///     a. This might include actions parsed but generally isolating the various stages is an easier to understand/maintain model<br/>
+///     b. Usually this is just app specific code that uses the bound results to adapt behavior<br/>
+///
+```
+
+Which one would ***YOU*** rather encounter in code? Which one is easier to understand when
+reading the source? This repo chooses the latter. (If you favor the former, perhaps you
+should reconsider... :grinning:)
+
+#### How to handle lists
+There is little that can be done to alter the rendering of any editor support, at most an
+editor might allow specification of a CSS file, but that is the lowest priority of doc
+comments. Readability by maintainers of the docs AND the rendering for final docs used by
+consumers of of VASTLY higher importance. Still, the editor rendering ***is*** of value to
+maintainers so should not be forgotten as it can make a "right mess of things" even if they
+render properly in final docs.
+
+##### Guidance
+1) ***DO NOT*** use `<para>` tags to include any lists
+    a) Doing so will break the docfx rendering that allows for markdown lists
+2) Use `</br>' tags to indicate a line break. This is used by the editor rendering to mark
+   the end of a line and start a new one. (Stops auto reflow)
+3) Accept that the in edotr rendering might "trim" the lines it shows, eliminating any
+   indentation.
+    a) Sadly, there is no avoiding this. Addition of any sort of "markup" to control that
+       will interfere with the readability AND the final docs rendering.
+4) Always use a different numbering style for sub lists/items
+    b) This will at least show in the in-editor rendering as distinct sub items so if
+       everything is trimmed it is at least a distinct pattern that is readable.
+5) ***DO NOT*** put lists in any place other than inside a `remarks` region
+    a) Usually, the remarks comments are not even rendered as the most useful part is the
+        API signaure and parameter info. Different editors may allow control of that.
+        i) In VS [2019|2022] for C# it is controlled by
+            `Text Editor > C# > Advanced > Editor Help: "Show remarks in Quick Info."`
+        ii) Turning this off can greatly reduce the noise AND reduce the problems of
+            different rende
+
diff --git a/docfx/SrcGeneration/api/index.md b/docfx/SrcGeneration/api/index.md
@@ -0,0 +1,6 @@
+# Ubiquity.NET.SrcGeneration
+This library contains support functionality to aid in building a source generator.
+This library is multi-targetting to allow consumption from a Roslyn source generator
+or VSIX project. Other uses should leverage the modern runtimes but those cases
+***MUST*** target only `.NET Standard 2.0`
+
diff --git a/docfx/SrcGeneration/index.md b/docfx/SrcGeneration/index.md
@@ -0,0 +1,6 @@
+# Ubiquity.NET.SrcGeneration
+This library contains support functionality to aid in building a source generator.
+This library is multi-targetting to allow consumption from a Roslyn source generator
+or VSIX project. Other uses should leverage the modern runtimes but those cases
+***MUST*** target only `.NET Standard 2.0`
+
diff --git a/docfx/SrcGeneration/toc.yml b/docfx/SrcGeneration/toc.yml
@@ -0,0 +1,5 @@
+# TOC (Left nav) for SrcGeneration folder
+- name: Overview
+  href: index.md
+- name: Namespaces
+  href: api/toc.yml
diff --git a/docfx/antlr-utils/toc.yml b/docfx/antlr-utils/toc.yml
@@ -1,4 +1,4 @@
-# TOC (Left nav) for LLVM folder
+# TOC (Left nav) for antly-utils folder
 - name: Overview
   href: index.md
 - name: Namespaces