Merge pull request #299 from smaillet/DocsForTextUx

Author: smaillet

docfx/TextUX/api/index.md

@@ -0,0 +1,2 @@
+# About
+Ubiquity.NET.TextUX contains general extensions for .NET. to support console (text) based applications

docfx/TextUX/index.md

@@ -0,0 +1,2 @@
+# About
+Ubiquity.NET.TextUX contains general extensions for .NET. to support console (text) based applications

docfx/TextUX/toc.yml

@@ -0,0 +1,5 @@
+# TOC (Left nav) for the 'extensions' folder
+- name: Overview
+  href: index.md
+- name: Namespaces
+  href: api/toc.yml

docfx/docfx.json

@@ -63,6 +63,18 @@
                 }
             ],
             "dest": "interop-helpers/api"
+        },
+        {
+            // TextUX  library
+            "memberLayout":"separatePages",
+            "namespaceLayout":"nested",
+            "src": [
+                {
+                    "src": "../src/Ubiquity.NET.TextUX",
+                    "files": ["**.csproj"]
+                }
+            ],
+            "dest": "TextUX/api"
         }
     ],
     "build": {
@@ -154,6 +166,18 @@
                     "**/namespaces/**.md",
                     "**/*-xref.yml"
                 ]
+            },
+            {
+                // TextUX project additional content, Includes the generated metadata API folder
+                // NOTE: File paths are relative to the location of this file
+                "files": [
+                    "TextUX/**.{md,yml}"
+                ],
+                // Exclude the namespace overwrites and XREF maps as they are listed explicitly elsewhere
+                "exclude": [
+                    "**/namespaces/**.md",
+                    "**/*-xref.yml"
+                ]
             }
         ],
         "resource": [

docfx/documentation.msbuildproj

@@ -55,6 +55,12 @@
     <!-- Explicitly call out the non-generated files in the API folder-->
     <None Include="interop-helpers/api/index.md" />
   </ItemGroup>
+  <ItemGroup>
+    <!--Everything in the TextUX sub-folders except the API folder as that contains generated files -->
+    <None Include="TextUX/**" Exclude="TextUX/api/**" />
+    <!-- Explicitly call out the non-generated files in the API folder-->
+    <None Include="TextUX/api/index.md" />
+  </ItemGroup>
   <Target Name="AlwaysRun" BeforeTargets="AfterBuild">
     <Message Importance="High" Text="NOTE: Building $(MSBuildProjectFile) does NOTHING, docs are built using the docfx tool. This project is simply a convenient placeholder for organizing/editing files" />
   </Target>

docfx/index.md

@@ -14,4 +14,5 @@ included.
 | [Ubiquity.NET.Runtime.Utils](runtime-utils/index.md) | This library contains common support for DSL runtime and language implementors |
 | [Ubiquity.NET.Extensions](extensions/index.md) | This library contains general extensions and helpers for many scenarios using .NET |
 | [Ubiquity.NET.Antlr.Utils](antlr-utils/index.md) | This library contains extensions and helpers for using ANTLR with .NET |
+| [Ubiquity.NET.TextUX](TextUX/index.md) | This library contains extensions and helpers for Text User eXperience (UX) applications (console) |
 | [Ubiquity.NET.InteropHelpers](interop-helpers/index.md) | This library contains extensions and helpers for implementing interop support for native libraries |

docfx/toc.yml

@@ -17,5 +17,7 @@
       href: extensions/index.md
     - name: ANTLR Utilities
       href: antlr-utils/index.md
+    - name: TextUX Utilities
+      href: TextUX/index.md
     - name: Interop Helpers
       href: interop-helpers/index.md

src/Ubiquity.NET.TextUX/ColoredConsoleReporter.cs

@@ -18,6 +18,17 @@ public ColoredConsoleReporter( MsgLevel level = MsgLevel.Information)
         {
         }
 
+        /// <remarks>
+        /// This implementation will apply ANSI color code sequences to each message based on <paramref name="level"/>.
+        /// The colors are:
+        /// <list type="table">
+        /// <listheader><term>Level</term><description>Description</description></listheader>
+        /// <item><term><see cref="MsgLevel.Verbose"/></term><description> Default console color</description></item>
+        /// <item><term><see cref="MsgLevel.Information"/></term><description> Blue</description></item>
+        /// <item><term><see cref="MsgLevel.Warning"/></term><description> Yellow</description></item>
+        /// <item><term><see cref="MsgLevel.Error"/></term><description> Red</description></item>
+        /// </list>
+        /// </remarks>
         /// <inheritdoc/>
         protected override void ReportMessage( MsgLevel level, string msg )
         {

src/Ubiquity.NET.TextUX/ConsoleReporter.cs

@@ -2,15 +2,14 @@
 // Licensed under the Apache-2.0 WITH LLVM-exception license. See the LICENSE.md file in the project root for full license information.
 
 using System;
-using System.Globalization;
 using System.Text;
 
 namespace Ubiquity.NET.TextUX
 {
     /// <summary>Implementation of <see cref="IDiagnosticReporter"/> that reports messages to <see cref="Console"/></summary>
     /// <remarks>
-    /// <see cref="MsgLevel.Error"/> is reported to <see cref="Console.Error"/> while other levels, if
-    /// enabled, are reported to <see cref="Console.Out"/>
+    /// Messages with a <see cref="DiagnosticMessage.Level"/> of <see cref="MsgLevel.Error"/> are reported to the console's <see cref="Console.Error"/>
+    /// writer, while other levels, if enabled, are reported to the console's <see cref="Console.Out"/> writer.
     /// </remarks>
     public class ConsoleReporter
         : IDiagnosticReporter
@@ -34,7 +33,9 @@ public ConsoleReporter( MsgLevel level = MsgLevel.Information)
 
         /// <inheritdoc/>
         /// <remarks>
-        /// This implementation currently ignores the source of any diagnostics
+        /// This implementation will test if the <see cref="DiagnosticMessage.Level"/> of the
+        /// message is enabled. If so, then a call is made to the virtual <see cref="ReportMessage(MsgLevel, string)"/>
+        /// with the results of <see cref="DiagnosticMessage.ToString()"/> as the message text.
         /// </remarks>
         public void Report( DiagnosticMessage diagnostic )
         {
@@ -43,16 +44,16 @@ public void Report( DiagnosticMessage diagnostic )
                 return;
             }
 
-            ReportMessage(diagnostic.Level, diagnostic.ToString("G", CultureInfo.CurrentCulture));
+            ReportMessage(diagnostic.Level, diagnostic.ToString());
         }
 
         /// <summary>Virtual method to report a message formatted as a string</summary>
         /// <param name="level">Level of the message</param>
         /// <param name="msg">Message formatted as a string</param>
         /// <remarks>
         /// The default base implementation will simply redirect messages based on <paramref name="level"/> to
-        /// <see cref="Console.Error"/> if <paramref name="level"/> == <see cref="MsgLevel.Error"/> or <see cref="Console.Out"/>
-        /// for any other levels.
+        /// the console's <see cref="Console.Error"/> writer if <paramref name="level"/> == <see cref="MsgLevel.Error"/>
+        /// otherwise the <see cref="Console.Out"/> writer is used.
         /// </remarks>
         /// <exception cref="InvalidOperationException">Invalid/Unknown level - should never hit this, internal error if it does.</exception>
         protected virtual void ReportMessage(MsgLevel level, string msg)

src/Ubiquity.NET.TextUX/SourceRange.cs

@@ -35,7 +35,7 @@ public readonly record struct SourceRange
         public required SourcePosition End { get; init; }
 
         /// <summary>Gets a value indicating whether this instance can slice an input</summary>
-        /// <remarks>Attempts to slice an input when this is <see langword="false"/></remarks>
+        /// <remarks>Attempts to slice an input when this is <see langword="false"/> result in an empty string.</remarks>
         public bool CanSlice => Start.Index.HasValue && End.Index.HasValue;
 
         /// <summary>Gets the length of the range in characters if available</summary>
@@ -72,7 +72,10 @@ public string ToString( string? format, IFormatProvider? formatProvider )
         /// <returns>slice representing the characters of this range</returns>
         /// <exception cref="ArgumentOutOfRangeException">Thrown when the start or end of the range is not in range of the input source (&lt;0 or &gt;=Length)</exception>
         /// <remarks>
-        /// If <see cref="CanSlice"/> is <see langword="false"/> then this returns an empty span. (i.e., does not throw)
+        /// If <see cref="CanSlice"/> is <see langword="false"/> then this returns an empty span. (i.e., does not throw).
+        /// Slicing is only possible if BOTH the <see cref="Start"/> and <see cref="End"/> have an <see cref="SourcePosition.Index"/> value as
+        /// it is the index that is used to mark the start and end of the slice. Since various text sources track line positions uniquely
+        /// they are not reliable for slicing the source.
         /// </remarks>
         public ReadOnlySpan<char> Slice(ReadOnlySpan<char> source)
         {