Merge pull request #182 from ottobolyos/feat/docs-full-coverage

feat(docs): expand API reference to every committed project

Author: PatrickRitchie

.github/workflows/docs.yml

@@ -139,6 +139,15 @@ jobs:
         run: npx vitepress build
         env:
           DOCS_BASE: /MTConnect.NET/
+          # The flat 2 000-page API reference plus the unified server +
+          # client bundles push rollup past the GitHub Actions runner's
+          # default Node heap (~4 GB) during the markdown -> Vue
+          # transform. The previous symptom was 'Ineffective
+          # mark-compacts near heap limit' aborting the build with
+          # exit 134 even though no page actually fails to parse. Lift
+          # the cap to 8 GB -- runners have 16 GB of RAM, so this is
+          # well within budget.
+          NODE_OPTIONS: --max-old-space-size=8192
 
       # Upload the built artifact only on the deploy path. PR builds stop
       # after the build step (success / failure surfaces in the check).

agent/Processors/MTConnect.NET-AgentProcessor-Python/MTConnect.NET-AgentProcessor-Python.csproj

@@ -41,6 +41,17 @@
 			<PrivateAssets>all</PrivateAssets>
 		</PackageReference>
 		<PackageReference Include="NLog" Version="5.2.7" />
+		<!--
+		  IronPython's DynamicLanguageRuntime transitive (Microsoft.Scripting.dll)
+		  carries a strong-named reference to System.Configuration.ConfigurationManager
+		  8.0.0.0 even though its net8.0 nuspec drops the dependency (it was only
+		  declared on the netstandard2.0 group). Without an explicit reference here
+		  the assembly is never copied into bin/Debug/net8.0/, and `docfx metadata`
+		  emits `InvalidAssemblyReference` while walking the Python processor DLL's
+		  reference graph. Pinning it on the project that uses IronPython lands
+		  the assembly in the output directory so the docs build stays warning-free.
+		-->
+		<PackageReference Include="System.Configuration.ConfigurationManager" Version="8.0.0" />
 	</ItemGroup>
 
 	<ItemGroup>

docs/.docfx/docfx.json

@@ -25,10 +25,29 @@
             "agent/Modules/MTConnect.NET-AgentModule-MqttBroker/bin/Debug/net8.0/MTConnect.NET-AgentModule-MqttBroker.dll",
             "agent/Modules/MTConnect.NET-AgentModule-MqttRelay/bin/Debug/net8.0/MTConnect.NET-AgentModule-MqttRelay.dll",
             "agent/Modules/MTConnect.NET-AgentModule-ShdrAdapter/bin/Debug/net8.0/MTConnect.NET-AgentModule-ShdrAdapter.dll",
+            "agent/Processors/MTConnect.NET-AgentProcessor-Python/bin/Debug/net8.0/MTConnect.NET-AgentProcessor-Python.dll",
             "adapter/MTConnect.NET-Adapter/bin/Debug/net8.0/MTConnect.NET-Adapter.dll",
             "adapter/MTConnect.NET-Applications-Adapter/bin/Debug/net8.0/MTConnect.NET-Applications-Adapter.dll",
             "adapter/Modules/MTConnect.NET-AdapterModule-MQTT/bin/Debug/net8.0/MTConnect.NET-AdapterModule-MQTT.dll",
-            "adapter/Modules/MTConnect.NET-AdapterModule-SHDR/bin/Debug/net8.0/MTConnect.NET-AdapterModule-SHDR.dll"
+            "adapter/Modules/MTConnect.NET-AdapterModule-SHDR/bin/Debug/net8.0/MTConnect.NET-AdapterModule-SHDR.dll",
+            "build/MTConnect.NET-SysML-Import/bin/Debug/net8.0/MTConnect.NET-SysML-Import.dll",
+            "build/MTConnect.NET.Builder/bin/Debug/net8.0/MTConnect.NET.Builder.dll",
+            "examples/MTConnect.NET-Agent-Embedded/bin/Debug/net8.0/MTConnect.NET-Agent-Embedded.dll",
+            "examples/MTConnect.NET-Client-HTTP/bin/Debug/net8.0/MTConnect.NET-Client-HTTP.dll",
+            "examples/MTConnect.NET-Client-MQTT/bin/Debug/net8.0/MTConnect.NET-Client-MQTT.dll",
+            "examples/MTConnect.NET-Client-SHDR/bin/Debug/net8.0/MTConnect.NET-Client-SHDR.dll",
+            "templates/mtconnect.net-agent/content/MTConnect.NET-Embedded-Agent/bin/Debug/net8.0/agent.dll",
+            "tests/Compliance/MTConnect-Compliance-Tests/bin/Debug/net8.0/MTConnect-Compliance-Tests.dll",
+            "tests/MTConnect.NET-AgentModule-MqttRelay-Tests/bin/Debug/net8.0/MTConnect.NET-AgentModule-MqttRelay-Tests.dll",
+            "tests/MTConnect.NET-Common-Tests/bin/Debug/net8.0/MTConnect.NET-Common-Tests.dll",
+            "tests/MTConnect.NET-Docs-Tests/bin/Debug/net8.0/MTConnect.NET-Docs-Tests.dll",
+            "tests/MTConnect.NET-HTTP-Tests/bin/Debug/net8.0/MTConnect.NET-HTTP-Tests.dll",
+            "tests/MTConnect.NET-Integration-Tests/bin/Debug/net8.0/MTConnect.NET-Integration-Tests.dll",
+            "tests/MTConnect.NET-JSON-cppagent-Tests/bin/Debug/net8.0/MTConnect.NET-JSON-cppagent-Tests.dll",
+            "tests/MTConnect.NET-JSON-Tests/bin/Debug/net8.0/MTConnect.NET-JSON-Tests.dll",
+            "tests/MTConnect.NET-SHDR-Tests/bin/Debug/net8.0/MTConnect.NET-SHDR-Tests.dll",
+            "tests/MTConnect.NET-Tests-Agents/bin/Debug/net8.0/MTConnect.NET-Tests-Agents.dll",
+            "tests/MTConnect.NET-XML-Tests/bin/Debug/net8.0/MTConnect.NET-XML-Tests.dll"
           ],
           "src": "../.."
         }

docs/.docfx/filter.yml

@@ -2,6 +2,18 @@ apiRules:
   - exclude:
       uidRegex: ^Ceen($|\.)
       type: Namespace
+  # MTConnect.NET-DocsGen is the in-tree generator that produces the
+  # docs/api/ Markdown tree itself, not a shipped public surface. Its
+  # source DLL is intentionally absent from docfx.json, but the
+  # MTConnect.NET-Docs-Tests assembly references DocsGen, so its
+  # XML doc file (which embeds a six-space-indented bullet list of
+  # bare <c> tags that VitePress's Vue template parser rejects as
+  # "Element is missing end tag") is copy-local'd alongside the tests
+  # DLL and re-discovered by docfx. Filter out the namespace as the
+  # last-mile guard.
+  - exclude:
+      uidRegex: ^MTConnect\.NET_DocsGen($|\.)
+      type: Namespace
   # The legacy JSON v1 codec and the cppagent v2 codec each ship a type
   # named JsonProcessFeed{r,R}ate inside MTConnect.Assets.Json.CuttingTools.
   # The two pages collide on case-insensitive output paths (and on

docs/package.json

@@ -9,7 +9,7 @@
     "predev": "npm run regen",
     "dev": "vitepress dev",
     "prebuild": "npm run regen",
-    "build": "vitepress build",
+    "build": "node --max-old-space-size=8192 node_modules/vitepress/bin/vitepress.js build",
     "preview": "vitepress preview",
     "check-links": "node scripts/check-broken-links.mjs ."
   },

docs/reference/environment-variables.md

@@ -84,7 +84,7 @@ Every environment-variable reference discovered in the source tree. Both the C#
 
 | Kind | Source | Default / value | Context |
 | --- | --- | --- | --- |
-| `csharp-read` | [`tests/Compliance/MTConnect-Compliance-Tests/L2_CrossImpl/CppAgentParityWorkflowTests.cs:488`](https://github.com/TrakHound/MTConnect.NET/blob/master/tests/Compliance/MTConnect-Compliance-Tests/L2_CrossImpl/CppAgentParityWorkflowTests.cs#L488) |  | = Environment.GetEnvironmentVariable(FixtureDirEnv) |
+| `csharp-read` | [`tests/Compliance/MTConnect-Compliance-Tests/L2_CrossImpl/CppAgentParityWorkflowTests.cs:499`](https://github.com/TrakHound/MTConnect.NET/blob/master/tests/Compliance/MTConnect-Compliance-Tests/L2_CrossImpl/CppAgentParityWorkflowTests.cs#L499) |  | = Environment.GetEnvironmentVariable(FixtureDirEnv) |
 
 Adding a new `Environment.GetEnvironmentVariable("…")` call, a new `${MTCONNECT_…}` read in a contributor script, or a new `$env:MTCONNECT_…` reference in a PowerShell script without regenerating this page fails the validation test in CI.
 

docs/scripts/generate-api-ref.sh

@@ -1,9 +1,11 @@
 #!/usr/bin/env bash
 # Generate the API reference Markdown under docs/api/.
 #
-# Compiles every shipped MTConnect.NET library in Release / net8.0,
-# then runs `docfx metadata` against the produced DLLs and XML doc
-# files. The output is a flat tree of `Namespace.Type.md` pages
+# Compiles every committed MTConnect.NET project (libraries, agent and
+# adapter applications and modules, in-tree build / generator tools,
+# examples, the embedded-agent template, and the test suites) in
+# Debug, then runs `docfx metadata` against the produced DLLs and XML
+# doc files. The output is a flat tree of `Namespace.Type.md` pages
 # alongside per-namespace landing pages.
 #
 # Usage:
@@ -24,7 +26,7 @@ for arg in "$@"; do
   case "${arg}" in
     --fast) skip_build=true ;;
     -h|--help)
-      sed -n '2,15p' "${BASH_SOURCE[0]}"
+      sed -n '2,17p' "${BASH_SOURCE[0]}"
       exit 0
       ;;
     *)
@@ -34,6 +36,9 @@ for arg in "$@"; do
   esac
 done
 
+# Path to the project directory. The csproj filename is inferred as
+# "<basename>.csproj" except where overridden in the matching entries
+# of csproj_overrides below.
 projects=(
   "libraries/MTConnect.NET-Common"
   "libraries/MTConnect.NET-DeviceFinder"
@@ -56,24 +61,60 @@ projects=(
   "agent/Modules/MTConnect.NET-AgentModule-MqttBroker"
   "agent/Modules/MTConnect.NET-AgentModule-MqttRelay"
   "agent/Modules/MTConnect.NET-AgentModule-ShdrAdapter"
+  "agent/Processors/MTConnect.NET-AgentProcessor-Python"
   "adapter/MTConnect.NET-Adapter"
   "adapter/MTConnect.NET-Applications-Adapter"
   "adapter/Modules/MTConnect.NET-AdapterModule-MQTT"
   "adapter/Modules/MTConnect.NET-AdapterModule-SHDR"
+  "build/MTConnect.NET-SysML-Import"
+  "build/MTConnect.NET.Builder"
+  "examples/MTConnect.NET-Agent-Embedded"
+  "examples/MTConnect.NET-Client-HTTP"
+  "examples/MTConnect.NET-Client-MQTT"
+  "examples/MTConnect.NET-Client-SHDR"
+  "templates/mtconnect.net-agent/content/MTConnect.NET-Embedded-Agent:Agent.csproj"
+  "tests/Compliance/MTConnect-Compliance-Tests"
+  "tests/MTConnect.NET-AgentModule-MqttRelay-Tests"
+  "tests/MTConnect.NET-Common-Tests"
+  "tests/MTConnect.NET-Docs-Tests"
+  "tests/MTConnect.NET-HTTP-Tests"
+  "tests/MTConnect.NET-Integration-Tests"
+  "tests/MTConnect.NET-JSON-cppagent-Tests"
+  "tests/MTConnect.NET-JSON-Tests"
+  "tests/MTConnect.NET-SHDR-Tests"
+  "tests/MTConnect.NET-Tests-Agents"
+  "tests/MTConnect.NET-XML-Tests"
 )
 
 if ! "${skip_build}"; then
-  echo "==> building projects in Debug for net8.0"
-  # Debug is the multi-target config that compiles ONLY net8.0 on every
-  # project — Release multi-targets net4.6.1..net9.0 and fails on SDKs
-  # that lack the legacy reference assemblies. The reference is content,
-  # not packaged output, so a Debug build is fine.
-  for proj in "${projects[@]}"; do
-    name="$(basename "${proj}")"
-    dotnet build "${proj}/${name}.csproj" \
+  echo "==> building projects in Debug"
+  # Debug is the multi-target config that compiles ONLY net8.0 on
+  # every shipped project — Release multi-targets net4.6.1..net9.0 and
+  # fails on SDKs that lack the legacy reference assemblies. The
+  # reference is content, not packaged output, so a Debug build is
+  # fine.
+  for entry in "${projects[@]}"; do
+    proj_dir="${entry%%:*}"
+    if [[ "${entry}" == *:* ]]; then
+      csproj_name="${entry##*:}"
+    else
+      csproj_name="$(basename "${proj_dir}").csproj"
+    fi
+    # Pass no NoWarn overrides. TreatWarningsAsErrors=true in
+    # Directory.Build.props turns every XML-doc warning — including
+    # CS1591 (missing XML doc on a public surface) — into a build
+    # failure, which is the campaign's 100 % XML-doc-coverage gate.
+    #
+    # --no-incremental forces a from-source recompile. Without it,
+    # an obj/ tree that was last produced under a CS1591-suppressed
+    # build remains current and silently masks missing-doc errors:
+    # MSBuild's up-to-date check looks at file timestamps and skips
+    # csc altogether, so neither the new compiler flags nor the
+    # diagnostic list takes effect.
+    dotnet build "${proj_dir}/${csproj_name}" \
       -c Debug \
       -p:GenerateDocumentationFile=true \
-      -p:AdditionalNoWarn=CS1591 \
+      --no-incremental \
       --nologo \
       -v:quiet
   done
@@ -107,4 +148,72 @@ find docs/api -mindepth 1 -maxdepth 1 -not -name 'index.md' -exec rm -rf {} +
 find docs/api -name '*.md' -not -name 'index.md' -print0 \
   | xargs -0 sed -i -E 's#<code( [^>]*)?>#<code v-pre\1>#g'
 
+# docfx emits two C#-generic patterns whose opening `<` is bare while
+# the closing `>` is markdown-escaped as `\>`. Vue's template compiler
+# then treats the bare `<` as the start tag of an element that never
+# closes (the escaped `\>` is rendered as a literal `>` in HTML, not
+# as an end-tag token), tripping "Element is missing end tag" at
+# vitepress build time. The two patterns are:
+#
+#   1. Heading text after the anchor close, e.g.
+#      `### <a id="…"></a> Collect\(string, List<EnvVarInfo\>\)`.
+#   2. Return / parameter blocks where docfx renders an outer-generic
+#      link followed by an inner-generic link, e.g.
+#      ` [List](url-of-list)<[EnvVarInfo](url-of-envvarinfo)\>`.
+#
+# Both forms feed the parser a `<` followed by either an uppercase
+# letter (heading-text type name) or a `[` (markdown link opener) and
+# never close it with a real `</tag>`. Rewrite both bare opens as
+# `&lt;` HTML entities so the markdown -> HTML pipeline can't re-emit
+# a literal `<` (a backslash-escape would survive markdown but the
+# Vue template parser sees the rendered HTML, where `\<` decodes to
+# `<` again and re-trips the same error). The `<a id="…"></a>` anchor
+# itself is intentionally not touched -- `a` is lowercase, so the
+# `<[A-Z]` alternative misses it, and the `<\[` alternative is
+# unambiguous. Fenced code blocks render via the highlighter, not
+# Vue's template parser, so the bare generics they contain (e.g.
+# `public IReadOnlyList<EnvVarInfo> Collect(...)`) do not need
+# escaping. A small awk pass tracks ```-fence state and skips lines
+# inside fences so code-block content stays untouched.
+while IFS= read -r -d '' md_file; do
+  awk '
+    BEGIN { in_fence = 0 }
+    /^```/ { in_fence = !in_fence; print; next }
+    in_fence { print; next }
+    {
+      # Replace `<X` (uppercase) or `<[` with `&lt;X` / `&lt;[` by
+      # walking each match.
+      out = ""; s = $0
+      while (match(s, /<([A-Z]|\[)/)) {
+        out = out substr(s, 1, RSTART - 1) "&lt;" substr(s, RSTART + 1, RLENGTH - 1)
+        s = substr(s, RSTART + RLENGTH)
+      }
+      line = out s
+      # Replace `{{` with `&#123;&#123;` so Vue does not treat the
+      # token as a mustache interpolation. docfx preserves verbatim
+      # spec-marker text like `{{term(data set)}}` from XML doc
+      # comments, which Vue would otherwise try to parse as the
+      # JavaScript expression `term(data set)` and reject. The
+      # html-entity form survives the markdown -> HTML pipeline.
+      gsub(/\{\{/, "\\&#123;\\&#123;", line)
+      # Escape `*` inside <code ...>...</code> spans as `&#42;`.
+      # Without this, two `<code>*.sh</code>` spans on a single line
+      # let markdown-it treat the `*` characters as the bookends of
+      # an `<em>` span, producing `<em>.sh</code> and <code v-pre></em>`
+      # in the rendered HTML -- with the `<code>` open/close braces
+      # spliced into broken positions -- which then trips Vue with
+      # "Element is missing end tag" during vitepress build.
+      out2 = ""; t = line
+      while (match(t, /<code( [^>]*)?>[^<]*<\/code>/)) {
+        prefix = substr(t, 1, RSTART - 1)
+        span = substr(t, RSTART, RLENGTH)
+        gsub(/\*/, "\\&#42;", span)
+        out2 = out2 prefix span
+        t = substr(t, RSTART + RLENGTH)
+      }
+      print out2 t
+    }
+  ' "${md_file}" > "${md_file}.tmp" && mv "${md_file}.tmp" "${md_file}"
+done < <(find docs/api -name '*.md' -not -name 'index.md' -print0)
+
 echo "==> done. $(find docs/api -name '*.md' -not -name 'index.md' | wc -l) pages generated."

examples/MTConnect.NET-Agent-Embedded/Program.cs

@@ -14,24 +14,34 @@
 
 // [ Module Configuration ]
 // This is where you can create a custom configuration section
+/// <summary>Represents the module configuration.</summary>
 public class ModuleConfiguration
 {
+    /// <summary>Gets or sets the device uuid.</summary>
     public string DeviceUuid { get; set; }
+    /// <summary>Gets or sets the device name.</summary>
     public string DeviceName { get; set; }
+    /// <summary>Gets or sets the serial number.</summary>
     public string SerialNumber { get; set; }
 }
 
 
 
 // [ Agent Module ]
 // This is the module that runs your code
+/// <summary>Represents the module.</summary>
 public class Module : MTConnectInputAgentModule
 {
+    /// <summary>The configuration type id.</summary>
     public const string ConfigurationTypeId = "datasource"; // This must match the module section in the 'agent.config.yaml' file
+    /// <summary>The default id.</summary>
     public const string DefaultId = "DataSource Module"; // The ID is mainly just used for logging.
     private readonly ModuleConfiguration _configuration;
 
 
+    /// <summary>Initialises a new instance of the module type.</summary>
+    /// <param name="agent">The agent.</param>
+    /// <param name="configuration">The configuration.</param>
     public Module(IMTConnectAgentBroker agent, object configuration) : base(agent)
     {
         Id = DefaultId;

libraries/MTConnect.NET-DeviceFinder/MTConnectDeviceFinder.cs

@@ -125,7 +125,7 @@ public class MTConnectDeviceFinder
         public event RequestStatusHandler SearchCompleted;
 
 
-        /// <summary>Constructs the finder bound to the first reachable network interface; call <see cref="Start(int)"/> after configuring <see cref="Addresses"/> and <see cref="Ports"/>.</summary>
+        /// <summary>Constructs the finder bound to the first reachable network interface; call <see cref="Start(bool)"/> after configuring <see cref="Addresses"/> and <see cref="Ports"/>.</summary>
         public MTConnectDeviceFinder()
         {
             Init();

libraries/MTConnect.NET-HTTP/Clients/MTConnectHttpCurrentClient.cs

@@ -266,7 +266,7 @@ public async Task<IStreamsResponseDocument> GetAsync(CancellationToken cancellat
         }
 
 
-        /// <summary>Builds the <c>current</c> request URI from the client's own <see cref="MTConnectHttpClientRequest.Authority"/>, <see cref="MTConnectHttpClientRequest.Device"/>, <see cref="MTConnectHttpClientRequest.Path"/>, <see cref="At"/>, and <see cref="MTConnectHttpClientRequest.DocumentFormat"/>.</summary>
+        /// <summary>Builds the <c>current</c> request URI from the client's own <see cref="Authority"/>, <see cref="Device"/>, <see cref="Path"/>, <see cref="At"/>, and <see cref="DocumentFormat"/>.</summary>
         public Uri CreateUri() => CreateUri(Authority, Device, Path, At, DocumentFormat);
 
         /// <summary>Convenience overload that passes <c>0</c> for <paramref name="port"/>, taking the port from <paramref name="hostname"/> if present.</summary>