Additional doc updates for clarity in prep for release (#50)

smaillet · web-flow · commit 1570d92f9837 · 2025-06-26T11:16:40.000-07:00
* Updated docs (public/internal)
* Corrected typo in error message for script module

Co-authored-by: smaillet &lt;25911635+smaillet@users.noreply.github.com&gt;
diff --git a/PsModules/CommonBuild/Private/Get-VsArchitecture.ps1 b/PsModules/CommonBuild/Private/Get-VsArchitecture.ps1
@@ -6,6 +6,6 @@ function Get-VsArchitecture()
         X64 {'x64'}
         Arm {'ARM'}
         Arm64 {'ARM64'}
-        default { throw 'Usupported runtime architecture for MSVC'}
+        default { throw 'Unsupported runtime architecture for MSVC'}
     }
 }
diff --git a/PsModules/RepoBuild/Public/Initialize-BuildEnvironment.ps1 b/PsModules/RepoBuild/Public/Initialize-BuildEnvironment.ps1
@@ -32,9 +32,9 @@ function Initialize-BuildEnvironment
     values. In essence, the result is like a derived type from the common base. The
     additional properties added are:
 
-    | Name                       | Description                                                                                            |
-    |----------------------------|--------------------------------------------------------------------------------------------------------|
-    | OfficialGitRemoteUrl       | GIT Remote URL for ***this*** repository                                                               |
+    | Name                       | Description                              |
+    |----------------------------|------------------------------------------|
+    | OfficialGitRemoteUrl       | GIT Remote URL for ***this*** repository |
 #>
     # support common parameters
     [cmdletbinding()]
@@ -67,11 +67,6 @@ function Initialize-BuildEnvironment
         New-Item -ItemType Directory -Path $buildInfo['PackagesRoot'] -ErrorAction SilentlyContinue | Out-Null
         New-Item -ItemType Directory $buildInfo['NuGetOutputPath'] -ErrorAction SilentlyContinue | Out-Null
 
-        # Disable the default "terminal logger" support as it's a breaking change that should NEVER
-        # have been anything but OPT-IN. It's a terrible experience that ends up hiding/overwriting
-        # information and generally makes it HARDER to see what's going on, not easier as it claims.
-        $env:MSBUILDTERMINALLOGGER='off'
-
         return $buildInfo
     }
     catch
diff --git a/README.md b/README.md
@@ -50,15 +50,15 @@ of the last one released publicly.
 >
 > ***This implementation is making no assumptions and simply does NOT support the short form.***
 > That may seem like a hard stance but given the ambiguities of the spec, documenting the behavior
-> is difficult. Addditionally, handling all the potential variations makes for extremely complex
+> is difficult. Additionally, handling all the potential variations makes for extremely complex
 > implementation code. All of that for a feature in support of a NuGet client that is now obsolete.
 > (NuGet v3 can handle the full name just fine!). Thus, the lack of support in this library.
 
 ## End User Documentation
 Full documentation on the tasks is available in the project's [docs site](https://ubiquitydotnet.github.io/CSemVer.GitBuild/)
 
 ## Building the tasks
-Documentation on building and general maintencance of this repo are provided in the [Wiki](https://github.com/UbiquityDotNET/CSemVer.GitBuild/wiki).
+Documentation on building and general maintenance of this repo are provided in the [Wiki](https://github.com/UbiquityDotNET/CSemVer.GitBuild/wiki).
 
 ----
 <sup><a id="footnote_1">1</a></sup>See: [This issue](https://github.com/CK-Build/csemver.org/issues/2) which was reported upon
diff --git a/docfx/ReadMe.md b/docfx/ReadMe.md
@@ -54,7 +54,8 @@ There are a few folders containing input for the site generation.
 
 #### api-*
 These folders contain the Generated contents for each project as (YAML) metadata files
-parsed and generated from the source.
+parsed and generated from the source. Since most of these files are generated they are
+excluded from git in the [.gitignore](#gitignore) file.
 
 ##### api-*/Index.md
 This contains the main landing page for a given library it has the top bar navigation
@@ -68,8 +69,54 @@ set of namespaces, types, enums etc... Each library project generates it's own v
 of this file. 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
+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.
 >NOTE
 > The TOC.YML file format used in these topics is DIFFERENT from what is auto generated.
 >
+
+#### namespaces
+The `namespaces` folder contains overrides markdown files to allow documenting whole
+namespaces. .NET doc comments do not allow namespace documentation comments. However,
+docfx, when leveraged properly can. These files, when they include the correct YAML
+header are merged to the contents for the docs before generation of the final static
+site. This is enabled by adding the namespace content to the `overwrite` section of the
+docfx.json file:
+``` JSON
+{
+  "build":{
+    "content":[
+      "files":[
+        "<project dir>.**.{md,yml}"
+      ],
+      // Exclude the namespace overwrites as they are listed explicitly elsewhere
+      "exclude": [
+          "**/namespaces/**.md"
+      ]
+    ],
+    "overwrite": [
+      {
+        "files": [
+          "**/apidocs/**.md",
+          "**/namespaces/**.md"
+        ]
+      }
+    ],
+  }
+}
+```
+
+The YAML header should include the following:
+``` YAML
+---
+uid: <namespace UID>
+remarks: *content
+---
+```
+
+The `<namespace UID>` is usually just the full name of the namespace but is verifiable
+by examining the generated YML files in the [api-*](#api) folder. The `remarks` entry
+causes the contents of the file to merge to the contents of the remarks section. This
+will order the content ahead of the normally generated list of members. It is generally
+recommended to finish all such documents with a horizontal rule (`---` in markdown) to
+allow separation of the namespace remarks from the generated content. 
diff --git a/docfx/build-tasks/index.md b/docfx/build-tasks/index.md
@@ -238,7 +238,6 @@ $currentBuildKind = Get-CurrentBuildKind
 $env:IsAutomatedBuild = $currentBuildKind -ne [BuildKind]::LocalBuild
 $env:IsPullRequestBuild = $currentBuildKind -eq [BuildKind]::PullRequestBuild
 $env:IsReleaseBuild = $currentBuildKind -eq [BuildKind]::ReleaseBuild
-
 ```
 
 ## BuildVersion.xml
@@ -343,15 +342,18 @@ section of this document.
 | CSM204 | XML format of file specified by `$(BuildVersionXml)' is invalid |
 
 ----
-<sup><a id="footnote_1">1</a></sup> CSemVer-CI uses a latest build format and therefore all version numbers for a CI
-build, including local builds use a `Patch+1` pattern as defined by CSemVer-CI. This ensures
-that all forms of CI builds have a higher precedence than any release they are based on. To
-simplify that, a CI build contains everything in a given release and then some more. What
-release that will eventually become is intentionally undefined.
-
-
-<sup><a id="footnote_2">2</a></sup> CSM106 is essentially an internal sanity test. The props/targets files ensure that
-`$(CiBuildIndex)` and `$(CiBuildName)` have a value unless $(IsReleaseBuild) is set. In that case
-the targets file will force them to empty. So, there's no way to test for or hit this condition
-without completely replacing/bypassing the props/targets files for the task. Which is obviously,
-an unsupported scenario :grin:.
+<sup><a id="footnote_1">1</a></sup> CSemVer-CI uses a latest build format and therefore all
+version numbers for a CI build, including local builds use a `Patch+1` pattern as defined by
+CSemVer-CI. This ensures that all forms of CI builds have a higher precedence than any release
+they are based on. To clarify the understanding of that, a CI build contains everything in a
+given release and then some more. How much more, or what release that will eventually become
+is intentionally undefined. This allows selection of the final release version based on the
+contents of the actual changes. CI builds are understood unstable and subject to complete
+changes or even abandoned lines of thought.
+
+
+<sup><a id="footnote_2">2</a></sup> CSM106 is essentially an internal sanity test. The
+props/targets files ensure that `$(CiBuildIndex)` and `$(CiBuildName)` have a value unless
+$(IsReleaseBuild) is set. In that case the targets file will force them to empty. So, there's
+no way to test for or hit this condition without completely replacing/bypassing the props/targets
+files for the task. Which is obviously, an unsupported scenario :grin:.
diff --git a/docfx/index.md b/docfx/index.md
@@ -4,7 +4,6 @@ but the primary focus is automated build versioning that embraces the principal
 while conforming to the syntax of CSemVer and CSemVer-CI
 
 ## The Libraries in this repository
-(At least the ones generating docs at this point anyway! :grin:)
 
 | Library | Description |
 |---------|-------------|
@@ -13,12 +12,16 @@ while conforming to the syntax of CSemVer and CSemVer-CI
 
 >[!IMPORTANT]
 > There is confusion on the ordering of a CI build with relation to a release build with
-> CSemVer. A CI Build is either an initial build of an unreleased version with
-> [Major.Minor.Patch] == [0.0.0]. Or, it is based on the previously released version and is
-> [Major.Minor.Patch+1]. That is, a CI build is ordered BEFORE all release builds, or it
-> is ordered AFTER a specific release it is based on! In particular a CI build version does
-> ***NOT*** indicate what it will become when it is finally released, but what release it was
-> based on (If any).
+> CSemVer-CI. A CI Build is either an initial build of an unreleased version with
+> [Major.Minor.Patch] == [0.0.0]. Or, it is based on the previously released version and
+is [Major.Minor.Patch+1]. That is, a CI build is ordered BEFORE all release builds, or it
+> is ordered AFTER the specific release it is based on! In particular a CI build version
+> does ***NOT*** indicate what it will become when it is finally released, but what
+> release it was based on (If any). To simplify that, for clarity, a CI build contains
+> everything in the release it was based on and additional changes (that might remove
+> things). CI builds are, by definition NOT stable and consumers cannot rely on them for
+> predictions of future stability. A given CI build may even represent an abandoned
+> approach that never becomes a release!
 
 ---
 [Attributions](Attributions.md)
diff --git a/docfx/versioning-lib/index.md b/docfx/versioning-lib/index.md
@@ -4,9 +4,9 @@ The Ubiquity.NET.Versioning library provides types to support use of versioning
 2) [Constrained Semantic Versioning](https://csemver.org)
     - Including Continuous Integration (CI) via CSemVer-CI
 
-It is viable as a standalone package to allow validation of or comparisons to versions reported
-at runtime. (Especially from native interop that does not support package dependencies or
-versioning at runtime.)
+It is viable as a standalone package to allow validation of or comparisons to versions
+reported at runtime. (Especially from native interop that does not support package
+dependencies or versioning at runtime.)
 
 ## Example
 ``` C#
@@ -30,22 +30,26 @@ The library contains support for parsing of strings based on the rules of a
 SemVer, CSemVer, and CSemVer-CI
 
 ## Ordering
-The types all support `IComparable<T>`<sup>[1](#footnote_1)</sup> and properly handle correct sort ordering of the
-versions according to the rules of SemVer (Which, CSemVer and CSemVer-CI follow)
+The types all support `IComparable<T>`<sup>[1](#footnote_1)</sup> and properly handle
+correct sort ordering of the versions according to the rules of SemVer (Which, CSemVer
+and CSemVer-CI follow)
 
 >[!WARNING]
-> The formal 'spec' for [CSemVer](https://csemver.org) remains mostly silent on the point of
-> the short format. See this [known issue](https://github.com/CK-Build/csemver.org/issues/2).
+> The formal 'spec' for [CSemVer](https://csemver.org) remains mostly silent on the point
+> of the short format. See this [known issue](https://github.com/CK-Build/csemver.org/issues/2).
 > Since, the existence of that form was to support NuGet V2, which is now obsolete, this
-> library does not support the short form at all. (This choice keeps documentation clarity
-> [NOT SUPPORTED] and implementation simplicity)
+> library does not support the short form at all. (This choice keeps documentation
+> clarity [NOT SUPPORTED] and implementation simplicity)
 
 ------
-<sup><a id="footnote_1">1</a></sup> The `SemVer` class does NOT support `IComparable<T>` as
-the spec is not explicit on case sensitive comparison of AlphaNumeric Identifiers.
-Unfortunately, major repositories using SemVer have chosen to use different comparisons. Thus,
-a consumer is required to know a-priori if the version is compared insensitive or not.
-`IComparer<SemVer>` instances are available for both cases via the static class
-[SemVerComparer](xref:Ubiquity.NET.Versioning.SemVerComparer) and
-[CSmeVerComparer.CaseSensitive](xref:Ubiquity.NET.Versioning.SemVerComparer.CaseSensitive).
+<sup><a id="footnote_1">1</a></sup> The `SemVer` class does NOT support [`IComparable<T>`](xref:System.IComparable`1)
+as the spec is not explicit<sup>[2](#footnote_2)</sup> on case sensitive comparison of AlphaNumeric Identifiers.
+
+<sup><a id="footnote_2">2</a></sup>Technically the spec says that pre-release identifiers
+are compared lexicographically, which would mean they are case sensitive. Unfortunately,
+that was not made explicit and major repositories using SemVer have chosen to use
+different rules of comparison and ordering. Thus, a consumer is required to know a-priori
+if the version is compared insensitive or not. [`IComparer<SemVer>`](xref:System.Collections.Generic.IComparer{Ubiquity.NET.Versioning.SemVer})
+instances are available for both cases via the static class [SemVerComparer](xref:Ubiquity.NET.Versioning.SemVerComparer)
+and [CSmeVerComparer.CaseSensitive](xref:Ubiquity.NET.Versioning.SemVerComparer.CaseSensitive).
 
diff --git a/docfx/versioning-lib/namespaces/Ubiquit.NET.Versioning.md b/docfx/versioning-lib/namespaces/Ubiquit.NET.Versioning.md
@@ -2,8 +2,8 @@
 uid: Ubiquity.NET.Versioning
 remarks: *content
 ---
-This namespace contains the stand alone versioning support for the different forms of version
-information supported.
+This namespace contains the stand alone versioning support for the different forms of
+version information supported.
 
 ### Class Diagram
 The following diagram serves to illustrates the primary relationships between the various
@@ -55,32 +55,35 @@ classDiagram
     CSemVerCI "1" *-- CSemVer:BaseVersion
 ```
 >[!IMPORTANT]
-> There is no inheritance between a `SemVer`, `CSemVer`, and `CSemVerCI`. While conversion does
-> exist they are not completely compatible due the constraints of ALWAYS comparing case
-> insensitive for `CSemVer` and `CSemVerCI`
+> There is no inheritance between a `SemVer`, `CSemVer`, and `CSemVerCI`. While
+> conversion is possible in many cases they are not completely compatible due the
+> constraints on ranges and rules of ALWAYS comparing case insensitive for `CSemVer`
+> and `CSemVerCI`
 
 The primary differences between a generic SemVer, a CSemVer and CSemVerCI is in how the
-sequence of pre-release versioning components is handled and the constraints placed on the
-Major, Minor and Patch version numbers.
+sequence of pre-release versioning components is handled and the constraints placed on
+the Major, Minor and Patch version numbers.
 
 >[!NOTE]
-> A SemVer technically has no constraints on the range of the integral components and thus
-> a `BigInteger` is used. Though, in practical terms, if any of the components exceeds the
-> size of `UInt64` there's probably something wrong with how the thing the version applies
-> to is versioned :confused:. More realistically, CSemVer[-CI] constrains the integral
-> components to specific ranges to allow conversion to an ordered version and `FileVersionQuad`.
+> A SemVer technically has no constraints on the range of the integral components and
+> thus a `BigInteger` is used. Though, in practical terms, if any of the components
+> exceeds the size of `UInt64` there's probably something wrong with how the thing the
+> version applies to is versioned :confused:. More realistically, CSemVer[-CI]
+> constrains the integral components to specific ranges to allow conversion to an ordered
+> version and `FileVersionQuad`.
 
 
 >[!IMPORTANT]
-> A CSemVer[-CI] is ***ALWAYS*** ordered using a case-insensitive comparison for AlphaNumeric
-> Identifiers in the version. Sadly, the SemVer spec is not explicit on the point of case
-> sensitivity and various major implementations for popular frameworks have chosen different
-> approaches. Thus a consumer of a pure SemVer needs to know which kind of comparison to use
-> in order to get correct results.
-> Due to the ambiguity of case sensitivity in ordering, it is recommended that all uses of
-> SemVer in the real world use ALL the same case (All *UPPER* or all *lower*). This avoids
-> the confusion and produces correct ordering no matter what variant of comparison a consumer
-> uses. Problems come when the version uses a *Mixed* case format.
+> A CSemVer[-CI] is ***ALWAYS*** ordered using a case-insensitive comparison for
+> AlphaNumeric Identifiers in the version. Sadly, the SemVer spec is not explicit on the
+> point of case sensitivity and various major implementations for popular frameworks have
+> chosen different approaches. Thus a consumer of a pure SemVer needs to know which kind
+> of comparison to use in order to get correct results.
+>
+> Due to the ambiguity of case sensitivity in ordering, it is recommended that all uses
+> of SemVer in the real world use ALL the same case (All *UPPER* or all *lower*). This
+> avoids the confusion and produces correct ordering no matter what variant of comparison
+> a consumer uses. Problems come when the version uses a *Mixed* case format.
 
 ### CSemVer Constraints on the integral components
 In particular the values are constrained
@@ -93,11 +96,11 @@ as follows:
 | Patch | [0-9999]  |
 
 ## CSemVer constraints on the release sequence
-Technically, SemVer does not limit the number of components to a pre-release value. It could
-be ANY finite set. This is, of course unreasonable in the real world so CSemVer places
-constraints on the number of components AND attributes particular meaning to each part. A
-CSemVer may have up to three pre-release components that are interpreted according to the
-following table:
+Technically, SemVer does not limit the number of components to a pre-release value. It
+could be ANY finite set. This is, of course unreasonable in the real world so CSemVer
+places constraints on the number of components AND attributes particular meaning to each
+part. A CSemVer may have up to three pre-release components that are interpreted
+according to the following table:
 
 | Index | Name | Description |
 |-------|------|-------------|
@@ -121,14 +124,14 @@ The names of a pre-release are constrained in CSemVer[-CI] to the following:<sup
 
 ------
 <sup><a id="footnote_1">1</a></sup> This library does NOT support the short form of names in a
-CSemVer. The exact string representation of the short form of a CSemVer as specified is not
-entirely clear. (see:[this issue](https://github.com/CK-Build/csemver.org/issues/2)) This
-implementation has chosen to ignore the short form completely. Based on what little is said
-about it int the spec, it was created to support a limitation in NuGet v2, which is now
-obsolete. Thus, the libraries do not support producing strings using the short form, nor do
-they recognize one when parsing. 
-
-<sup><a id="footnote_2">2</a></sup> `prerelease` is always considered valid as well. Internally
-it is automatically converted to the shorter `pre` form.
+CSemVer. The exact string representation of the short form of a CSemVer as specified is
+not entirely clear. (see:[this issue](https://github.com/CK-Build/csemver.org/issues/2))
+This implementation has chosen to ignore the short form completely. Based on what little
+is said about it in the spec, it was created to support a limitation in NuGet v2, which
+is now obsolete. Thus, the libraries do not support producing strings using the short
+form, nor do they recognize one when parsing. 
+
+<sup><a id="footnote_2">2</a></sup> `prerelease` is always considered valid as well.
+Internally it is automatically converted to the shorter `pre` form.
 
 ----

Original file line number	Diff line number	Diff line change
`@@ -6,6 +6,6 @@ function Get-VsArchitecture()`
`6`	`6`	`X64 {'x64'}`
`7`	`7`	`Arm {'ARM'}`
`8`	`8`	`Arm64 {'ARM64'}`
`9`		`- default { throw 'Usupported runtime architecture for MSVC'}`
	`9`	`+ default { throw 'Unsupported runtime architecture for MSVC'}`
`10`	`10`	`}`
`11`	`11`	`}`