Skip to content

Commit 002470d

Browse files
ottobolyosottobolyos
committed
merge feat/docs-full-coverage (TrakHound#182) into integration
# Conflicts: # docs/.docfx/docfx.json # docs/scripts/generate-api-ref.sh
2 parents 5b3b45c + b6485d7 commit 002470d

150 files changed

Lines changed: 1092 additions & 31 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

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

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,17 @@
4141
<PrivateAssets>all</PrivateAssets>
4242
</PackageReference>
4343
<PackageReference Include="NLog" Version="5.2.7" />
44+
<!--
45+
IronPython's DynamicLanguageRuntime transitive (Microsoft.Scripting.dll)
46+
carries a strong-named reference to System.Configuration.ConfigurationManager
47+
8.0.0.0 even though its net8.0 nuspec drops the dependency (it was only
48+
declared on the netstandard2.0 group). Without an explicit reference here
49+
the assembly is never copied into bin/Debug/net8.0/, and `docfx metadata`
50+
emits `InvalidAssemblyReference` while walking the Python processor DLL's
51+
reference graph. Pinning it on the project that uses IronPython lands
52+
the assembly in the output directory so the docs build stays warning-free.
53+
-->
54+
<PackageReference Include="System.Configuration.ConfigurationManager" Version="8.0.0" />
4455
</ItemGroup>
4556

4657
<ItemGroup>

‎docs/.docfx/docfx.json‎

Lines changed: 21 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,10 +25,30 @@
2525
"agent/Modules/MTConnect.NET-AgentModule-MqttBroker/bin/Debug/net8.0/MTConnect.NET-AgentModule-MqttBroker.dll",
2626
"agent/Modules/MTConnect.NET-AgentModule-MqttRelay/bin/Debug/net8.0/MTConnect.NET-AgentModule-MqttRelay.dll",
2727
"agent/Modules/MTConnect.NET-AgentModule-ShdrAdapter/bin/Debug/net8.0/MTConnect.NET-AgentModule-ShdrAdapter.dll",
28+
"agent/Processors/MTConnect.NET-AgentProcessor-Python/bin/Debug/net8.0/MTConnect.NET-AgentProcessor-Python.dll",
2829
"adapter/MTConnect.NET-Adapter/bin/Debug/net8.0/MTConnect.NET-Adapter.dll",
2930
"adapter/MTConnect.NET-Applications-Adapter/bin/Debug/net8.0/MTConnect.NET-Applications-Adapter.dll",
3031
"adapter/Modules/MTConnect.NET-AdapterModule-MQTT/bin/Debug/net8.0/MTConnect.NET-AdapterModule-MQTT.dll",
31-
"adapter/Modules/MTConnect.NET-AdapterModule-SHDR/bin/Debug/net8.0/MTConnect.NET-AdapterModule-SHDR.dll"
32+
"adapter/Modules/MTConnect.NET-AdapterModule-SHDR/bin/Debug/net8.0/MTConnect.NET-AdapterModule-SHDR.dll",
33+
"build/MTConnect.NET-SysML-Import/bin/Debug/net8.0/MTConnect.NET-SysML-Import.dll",
34+
"build/MTConnect.NET-DocsGen/bin/Debug/net8.0/MTConnect.NET-DocsGen.dll",
35+
"build/MTConnect.NET.Builder/bin/Debug/net8.0/MTConnect.NET.Builder.dll",
36+
"examples/MTConnect.NET-Agent-Embedded/bin/Debug/net8.0/MTConnect.NET-Agent-Embedded.dll",
37+
"examples/MTConnect.NET-Client-HTTP/bin/Debug/net8.0/MTConnect.NET-Client-HTTP.dll",
38+
"examples/MTConnect.NET-Client-MQTT/bin/Debug/net8.0/MTConnect.NET-Client-MQTT.dll",
39+
"examples/MTConnect.NET-Client-SHDR/bin/Debug/net8.0/MTConnect.NET-Client-SHDR.dll",
40+
"templates/mtconnect.net-agent/content/MTConnect.NET-Embedded-Agent/bin/Debug/net8.0/agent.dll",
41+
"tests/Compliance/MTConnect-Compliance-Tests/bin/Debug/net8.0/MTConnect-Compliance-Tests.dll",
42+
"tests/MTConnect.NET-AgentModule-MqttRelay-Tests/bin/Debug/net8.0/MTConnect.NET-AgentModule-MqttRelay-Tests.dll",
43+
"tests/MTConnect.NET-Common-Tests/bin/Debug/net8.0/MTConnect.NET-Common-Tests.dll",
44+
"tests/MTConnect.NET-Docs-Tests/bin/Debug/net8.0/MTConnect.NET-Docs-Tests.dll",
45+
"tests/MTConnect.NET-HTTP-Tests/bin/Debug/net8.0/MTConnect.NET-HTTP-Tests.dll",
46+
"tests/MTConnect.NET-Integration-Tests/bin/Debug/net8.0/MTConnect.NET-Integration-Tests.dll",
47+
"tests/MTConnect.NET-JSON-cppagent-Tests/bin/Debug/net8.0/MTConnect.NET-JSON-cppagent-Tests.dll",
48+
"tests/MTConnect.NET-JSON-Tests/bin/Debug/net8.0/MTConnect.NET-JSON-Tests.dll",
49+
"tests/MTConnect.NET-SHDR-Tests/bin/Debug/net8.0/MTConnect.NET-SHDR-Tests.dll",
50+
"tests/MTConnect.NET-Tests-Agents/bin/Debug/net8.0/MTConnect.NET-Tests-Agents.dll",
51+
"tests/MTConnect.NET-XML-Tests/bin/Debug/net8.0/MTConnect.NET-XML-Tests.dll"
3252
],
3353
"src": "../.."
3454
}

‎docs/scripts/generate-api-ref.sh‎

Lines changed: 55 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,11 @@
11
#!/usr/bin/env bash
22
# Generate the API reference Markdown under docs/api/.
33
#
4-
# Compiles every shipped MTConnect.NET library in Release / net8.0,
5-
# then runs `docfx metadata` against the produced DLLs and XML doc
6-
# files. The output is a flat tree of `Namespace.Type.md` pages
4+
# Compiles every committed MTConnect.NET project (libraries, agent and
5+
# adapter applications and modules, in-tree build / generator tools,
6+
# examples, the embedded-agent template, and the test suites) in
7+
# Debug, then runs `docfx metadata` against the produced DLLs and XML
8+
# doc files. The output is a flat tree of `Namespace.Type.md` pages
79
# alongside per-namespace landing pages.
810
#
911
# Usage:
@@ -24,7 +26,7 @@ for arg in "$@"; do
2426
case "${arg}" in
2527
--fast) skip_build=true ;;
2628
-h|--help)
27-
sed -n '2,15p' "${BASH_SOURCE[0]}"
29+
sed -n '2,17p' "${BASH_SOURCE[0]}"
2830
exit 0
2931
;;
3032
*)
@@ -34,6 +36,9 @@ for arg in "$@"; do
3436
esac
3537
done
3638

39+
# Path to the project directory. The csproj filename is inferred as
40+
# "<basename>.csproj" except where overridden in the matching entries
41+
# of csproj_overrides below.
3742
projects=(
3843
"libraries/MTConnect.NET-Common"
3944
"libraries/MTConnect.NET-DeviceFinder"
@@ -56,24 +61,61 @@ projects=(
5661
"agent/Modules/MTConnect.NET-AgentModule-MqttBroker"
5762
"agent/Modules/MTConnect.NET-AgentModule-MqttRelay"
5863
"agent/Modules/MTConnect.NET-AgentModule-ShdrAdapter"
64+
"agent/Processors/MTConnect.NET-AgentProcessor-Python"
5965
"adapter/MTConnect.NET-Adapter"
6066
"adapter/MTConnect.NET-Applications-Adapter"
6167
"adapter/Modules/MTConnect.NET-AdapterModule-MQTT"
6268
"adapter/Modules/MTConnect.NET-AdapterModule-SHDR"
69+
"build/MTConnect.NET-SysML-Import"
70+
"build/MTConnect.NET-DocsGen"
71+
"build/MTConnect.NET.Builder"
72+
"examples/MTConnect.NET-Agent-Embedded"
73+
"examples/MTConnect.NET-Client-HTTP"
74+
"examples/MTConnect.NET-Client-MQTT"
75+
"examples/MTConnect.NET-Client-SHDR"
76+
"templates/mtconnect.net-agent/content/MTConnect.NET-Embedded-Agent:Agent.csproj"
77+
"tests/Compliance/MTConnect-Compliance-Tests"
78+
"tests/MTConnect.NET-AgentModule-MqttRelay-Tests"
79+
"tests/MTConnect.NET-Common-Tests"
80+
"tests/MTConnect.NET-Docs-Tests"
81+
"tests/MTConnect.NET-HTTP-Tests"
82+
"tests/MTConnect.NET-Integration-Tests"
83+
"tests/MTConnect.NET-JSON-cppagent-Tests"
84+
"tests/MTConnect.NET-JSON-Tests"
85+
"tests/MTConnect.NET-SHDR-Tests"
86+
"tests/MTConnect.NET-Tests-Agents"
87+
"tests/MTConnect.NET-XML-Tests"
6388
)
6489

6590
if ! "${skip_build}"; then
66-
echo "==> building projects in Debug for net8.0"
67-
# Debug is the multi-target config that compiles ONLY net8.0 on every
68-
# project — Release multi-targets net4.6.1..net9.0 and fails on SDKs
69-
# that lack the legacy reference assemblies. The reference is content,
70-
# not packaged output, so a Debug build is fine.
71-
for proj in "${projects[@]}"; do
72-
name="$(basename "${proj}")"
73-
dotnet build "${proj}/${name}.csproj" \
91+
echo "==> building projects in Debug"
92+
# Debug is the multi-target config that compiles ONLY net8.0 on
93+
# every shipped project — Release multi-targets net4.6.1..net9.0 and
94+
# fails on SDKs that lack the legacy reference assemblies. The
95+
# reference is content, not packaged output, so a Debug build is
96+
# fine.
97+
for entry in "${projects[@]}"; do
98+
proj_dir="${entry%%:*}"
99+
if [[ "${entry}" == *:* ]]; then
100+
csproj_name="${entry##*:}"
101+
else
102+
csproj_name="$(basename "${proj_dir}").csproj"
103+
fi
104+
# Pass no NoWarn overrides. TreatWarningsAsErrors=true in
105+
# Directory.Build.props turns every XML-doc warning — including
106+
# CS1591 (missing XML doc on a public surface) — into a build
107+
# failure, which is the campaign's 100 % XML-doc-coverage gate.
108+
#
109+
# --no-incremental forces a from-source recompile. Without it,
110+
# an obj/ tree that was last produced under a CS1591-suppressed
111+
# build remains current and silently masks missing-doc errors:
112+
# MSBuild's up-to-date check looks at file timestamps and skips
113+
# csc altogether, so neither the new compiler flags nor the
114+
# diagnostic list takes effect.
115+
dotnet build "${proj_dir}/${csproj_name}" \
74116
-c Debug \
75117
-p:GenerateDocumentationFile=true \
76-
-p:AdditionalNoWarn=CS1591 \
118+
--no-incremental \
77119
--nologo \
78120
-v:quiet
79121
done

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

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,24 +14,34 @@
1414

1515
// [ Module Configuration ]
1616
// This is where you can create a custom configuration section
17+
/// <summary>Represents the module configuration.</summary>
1718
public class ModuleConfiguration
1819
{
20+
/// <summary>Gets or sets the device uuid.</summary>
1921
public string DeviceUuid { get; set; }
22+
/// <summary>Gets or sets the device name.</summary>
2023
public string DeviceName { get; set; }
24+
/// <summary>Gets or sets the serial number.</summary>
2125
public string SerialNumber { get; set; }
2226
}
2327

2428

2529

2630
// [ Agent Module ]
2731
// This is the module that runs your code
32+
/// <summary>Represents the module.</summary>
2833
public class Module : MTConnectInputAgentModule
2934
{
35+
/// <summary>The configuration type id.</summary>
3036
public const string ConfigurationTypeId = "datasource"; // This must match the module section in the 'agent.config.yaml' file
37+
/// <summary>The default id.</summary>
3138
public const string DefaultId = "DataSource Module"; // The ID is mainly just used for logging.
3239
private readonly ModuleConfiguration _configuration;
3340

3441

42+
/// <summary>Initialises a new instance of the module type.</summary>
43+
/// <param name="agent">The agent.</param>
44+
/// <param name="configuration">The configuration.</param>
3545
public Module(IMTConnectAgentBroker agent, object configuration) : base(agent)
3646
{
3747
Id = DefaultId;

‎libraries/MTConnect.NET-DeviceFinder/MTConnectDeviceFinder.cs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -125,7 +125,7 @@ public class MTConnectDeviceFinder
125125
public event RequestStatusHandler SearchCompleted;
126126

127127

128-
/// <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>
128+
/// <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>
129129
public MTConnectDeviceFinder()
130130
{
131131
Init();

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -266,7 +266,7 @@ public async Task<IStreamsResponseDocument> GetAsync(CancellationToken cancellat
266266
}
267267

268268

269-
/// <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>
269+
/// <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>
270270
public Uri CreateUri() => CreateUri(Authority, Device, Path, At, DocumentFormat);
271271

272272
/// <summary>Convenience overload that passes <c>0</c> for <paramref name="port"/>, taking the port from <paramref name="hostname"/> if present.</summary>

‎libraries/MTConnect.NET-HTTP/Clients/MTConnectHttpProbeClient.cs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -313,7 +313,7 @@ public async Task<IDevicesResponseDocument> GetAsync(CancellationToken cancellat
313313
}
314314

315315

316-
/// <summary>Builds the <c>probe</c> request URI from the client's own <see cref="MTConnectHttpClientRequest.Authority"/>, <see cref="MTConnectHttpClientRequest.Device"/>, and <see cref="MTConnectHttpClientRequest.DocumentFormat"/>.</summary>
316+
/// <summary>Builds the <c>probe</c> request URI from the client's own <see cref="Authority"/>, <see cref="Device"/>, and <see cref="DocumentFormat"/>.</summary>
317317
public Uri CreateUri() => CreateUri(Authority, Device, DocumentFormat);
318318

319319
/// <summary>Convenience overload that passes <c>0</c> for <paramref name="port"/>, taking the port from <paramref name="hostname"/> if present.</summary>

‎libraries/MTConnect.NET-HTTP/Clients/MTConnectHttpSampleClient.cs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -283,7 +283,7 @@ public async Task<IStreamsResponseDocument> GetAsync(CancellationToken cancel)
283283
}
284284

285285

286-
/// <summary>Builds the <c>sample</c> request URI from the client's own <see cref="MTConnectHttpClientRequest.Authority"/>, <see cref="MTConnectHttpClientRequest.Device"/>, <see cref="MTConnectHttpClientRequest.Path"/>, <see cref="From"/>, <see cref="To"/>, <see cref="Count"/>, and <see cref="MTConnectHttpClientRequest.DocumentFormat"/>.</summary>
286+
/// <summary>Builds the <c>sample</c> request URI from the client's own <see cref="Authority"/>, <see cref="Device"/>, <see cref="Path"/>, <see cref="From"/>, <see cref="To"/>, <see cref="Count"/>, and <see cref="DocumentFormat"/>.</summary>
287287
public Uri CreateUri() => CreateUri(Authority, Device, Path, From, To, Count, DocumentFormat);
288288

289289
/// <summary>Convenience overload that passes <c>0</c> for <paramref name="port"/>, so the port is taken from <paramref name="hostname"/> if it carries one.</summary>

‎libraries/MTConnect.NET-JSON-cppagent/Streams/JsonCell.cs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ namespace MTConnect.Streams.Json
1010
/// JSON serialization surrogate for a single cell of a table-entry
1111
/// observation. Carried inside a <see cref="JsonEntry"/>'s cell
1212
/// list when expressed as discrete cell objects, before the parent
13-
/// <see cref="JsonTableEntries"/> converter collapses cells into
13+
/// <see cref="MTConnect.NET_JSON_cppagent.Streams.JsonTableEntries"/> converter collapses cells into
1414
/// the row dictionary on emission.
1515
/// </summary>
1616
public class JsonCell

‎libraries/MTConnect.NET-MQTT/Configurations/IMTConnectMqttDocumentServerConfiguration.cs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
namespace MTConnect.Configurations
55
{
66
/// <summary>
7-
/// Settings consumed by <see cref="MTConnect.Mqtt.MTConnectMqttDocumentServer"/> that publish
7+
/// Settings consumed by <c>MTConnect.Mqtt.MTConnectMqttDocumentServer</c> (defined in the agent MQTT modules) that publish
88
/// the full MTConnect response documents (Probe, Current, Sample, Asset) over MQTT rather
99
/// than individual observation topics. Configures only the publish cadence; the topic layout
1010
/// is defined by the concrete configuration class.

0 commit comments

Comments
 (0)