Switch API docs from DefaultDocumentation to ApiMark

.config/dotnet-tools.json

@@ -6,61 +6,71 @@
       "version": "11.2.1",
       "commands": [
         "dotnet-sonarscanner"
-      ]
+      ],
+      "rollForward": false
     },
     "demaconsulting.pandoctool": {
       "version": "3.9.0.2",
       "commands": [
         "pandoc"
-      ]
+      ],
+      "rollForward": false
     },
     "demaconsulting.weasyprinttool": {
       "version": "68.1.0",
       "commands": [
         "weasyprint"
-      ]
+      ],
+      "rollForward": false
     },
     "demaconsulting.sarifmark": {
       "version": "1.3.2",
       "commands": [
         "sarifmark"
-      ]
+      ],
+      "rollForward": false
     },
     "demaconsulting.sonarmark": {
       "version": "1.5.0",
       "commands": [
         "sonarmark"
-      ]
+      ],
+      "rollForward": false
     },
     "demaconsulting.reqstream": {
       "version": "1.10.0",
       "commands": [
         "reqstream"
-      ]
+      ],
+      "rollForward": false
     },
     "demaconsulting.buildmark": {
       "version": "1.2.2",
       "commands": [
         "buildmark"
-      ]
+      ],
+      "rollForward": false
     },
     "demaconsulting.versionmark": {
       "version": "1.4.3",
       "commands": [
         "versionmark"
-      ]
+      ],
+      "rollForward": false
     },
     "demaconsulting.reviewmark": {
       "version": "1.2.0",
       "commands": [
         "reviewmark"
-      ]
+      ],
+      "rollForward": false
     },
     "demaconsulting.fileassert": {
       "version": "0.3.0",
       "commands": [
         "fileassert"
-      ]
+      ],
+      "rollForward": false
     }
   }
 }

.github/workflows/build.yaml

@@ -341,6 +341,21 @@ jobs:
       - name: Install npm dependencies
         run: npm install
 
+      - name: Set browser path for Mermaid (Windows)
+        shell: pwsh
+        run: |
+          $chromePaths = @(
+            "C:\Program Files\Google\Chrome\Application\chrome.exe",
+            "C:\Program Files (x86)\Google\Chrome\Application\chrome.exe"
+          )
+          foreach ($path in $chromePaths) {
+            if (Test-Path $path) {
+              "PUPPETEER_EXECUTABLE_PATH=$path" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
+              Write-Host "Set PUPPETEER_EXECUTABLE_PATH to $path"
+              break
+            }
+          }
+
       - name: Restore Tools
         run: dotnet tool restore
 

README.md

@@ -121,35 +121,13 @@ SpdxRelationships.Add(document, relationship);
 var rootPackages = document.GetRootPackages();
 ```
 
-## API Overview
+## API Documentation
 
-### Core Classes
-
-- **`SpdxDocument`** - Represents an SPDX document
-- **`SpdxPackage`** - Represents a software package
-- **`SpdxFile`** - Represents a file
-- **`SpdxSnippet`** - Represents a code snippet
-- **`SpdxRelationship`** - Represents relationships between elements
-- **`SpdxCreationInformation`** - Document creation metadata
-- **`SpdxAnnotation`** - Represents document annotations
-- **`SpdxChecksum`** - Represents element checksums
-- **`SpdxExternalDocumentReference`** - Represents external document references
-- **`SpdxExternalReference`** - Represents external references on packages
-- **`SpdxExtractedLicensingInfo`** - Represents extracted licensing information
-- **`SpdxPackageVerificationCode`** - Represents package verification codes
-
-### Serialization
-
-- **`Spdx2JsonSerializer`** - Serialize SPDX documents to JSON
-- **`Spdx2JsonDeserializer`** - Deserialize SPDX documents from JSON
-
-### Transforms
-
-- **`SpdxRelationships`** - Utilities for managing relationships
+Detailed API documentation for all public types and members is distributed in the `api/` folder
+of the NuGet package.
 
 ## Documentation
 
-- [API Documentation](https://github.com/demaconsulting/SpdxModel/wiki) - Detailed API reference
 - [Contributing Guide][contributing] - How to contribute to the project
 - [Code of Conduct][code-of-conduct] - Community guidelines
 - [Security Policy][security] - Security vulnerability reporting

src/DemaConsulting.SpdxModel/DemaConsulting.SpdxModel.csproj

@@ -51,6 +51,7 @@
     <PackageReference Include="Microsoft.Sbom.Targets" Version="4.1.5" PrivateAssets="All" />
     <PackageReference Include="Polyfill" Version="10.7.0" PrivateAssets="All" />
     <PackageReference Include="Microsoft.SourceLink.GitHub" Version="10.0.300" PrivateAssets="All" />
+    <PackageReference Include="DemaConsulting.ApiMark.MSBuild" Version="0.1.3" PrivateAssets="All" />
   </ItemGroup>
 
   <!-- Code Analysis Dependencies -->
@@ -89,4 +90,17 @@
     <None Include="..\..\Icon.png" Pack="true" PackagePath="\" />
   </ItemGroup>
 
+  <!-- API documentation generation -->
+  <PropertyGroup>
+    <!-- Run API documentation generation only for this framework in multi-targeted builds -->
+    <ApiDocsTargetFramework>netstandard2.0</ApiDocsTargetFramework>
+    <!-- Configuration-specific output so Debug and Release docs do not overwrite each other -->
+    <ApiMarkOutputDir>$(MSBuildProjectDirectory)/bin/$(Configuration)/apimark-docs</ApiMarkOutputDir>
+    <!-- Pack generated API docs into the NuGet package under api/ -->
+    <ApiMarkPackDocs>false</ApiMarkPackDocs>
+    <ApiMarkPackDocs Condition="'$(TargetFramework)' == '' Or '$(TargetFramework)' == '$(ApiDocsTargetFramework)'">true</ApiMarkPackDocs>
+    <!-- Disable for non-primary framework to avoid duplicate generation in multi-targeted builds; outer build (empty TargetFramework) is the packaging context and must not be disabled -->
+    <DisableApiMark Condition="'$(TargetFramework)' != '' And '$(TargetFramework)' != '$(ApiDocsTargetFramework)'">true</DisableApiMark>
+  </PropertyGroup>
+
 </Project>

src/DemaConsulting.SpdxModel/IO/Spdx2JsonDeserializer.cs

@@ -42,6 +42,12 @@ public static class Spdx2JsonDeserializer
     /// <param name="json">Json string</param>
     /// <returns>SPDX Document</returns>
     /// <exception cref="JsonException">Thrown when <paramref name="json"/> is not valid JSON text or does not represent a JSON object.</exception>
+    /// <example>
+    ///     <code>
+    ///     string json = File.ReadAllText("sbom.spdx.json");
+    ///     SpdxDocument document = Spdx2JsonDeserializer.Deserialize(json);
+    ///     </code>
+    /// </example>
     public static SpdxDocument Deserialize(string json)
     {
         // Deserialize the Json

src/DemaConsulting.SpdxModel/IO/Spdx2JsonSerializer.cs

@@ -48,6 +48,12 @@ public static class Spdx2JsonSerializer
     ///     Indented JSON string conforming to the SPDX 2.3 schema. All optional fields
     ///     absent from the model are omitted from the output.
     /// </returns>
+    /// <example>
+    ///     <code>
+    ///     string json = Spdx2JsonSerializer.Serialize(document);
+    ///     File.WriteAllText("sbom.spdx.json", json);
+    ///     </code>
+    /// </example>
     public static string Serialize(SpdxDocument document)
     {
         // Serialize the document

src/DemaConsulting.SpdxModel/SpdxDocument.cs

@@ -35,6 +35,21 @@ namespace DemaConsulting.SpdxModel;
 /// </remarks>
 public sealed class SpdxDocument : SpdxElement
 {
+    /// <summary>
+    ///     Initializes a new instance of the <see cref="SpdxDocument"/> class with default values.
+    /// </summary>
+    /// <remarks>
+    ///     All collection properties are initialized to empty arrays and all non-nullable scalar string
+    ///     properties to <see cref="string.Empty"/>; nullable string properties (such as
+    ///     <see cref="Comment"/>) remain <see langword="null"/> unless explicitly set.
+    ///     <see cref="CreationInformation"/> is initialized to a new default
+    ///     <see cref="SpdxCreationInformation"/> instance. The default constructor is provided
+    ///     explicitly so that consumers can document and discover it through the API reference.
+    /// </remarks>
+    public SpdxDocument()
+    {
+    }
+
     /// <summary>
     ///     Regular expression for checking SPDX version fields
     /// </summary>
@@ -151,23 +166,23 @@ public sealed class SpdxDocument : SpdxElement
     public SpdxAnnotation[] Annotations { get; set; } = [];
 
     /// <summary>
-    ///     Files
+    ///     SPDX file elements described in this document
     /// </summary>
     /// <remarks>
     ///     All file elements described in this SPDX document as defined in SPDX 2.x §4.
     /// </remarks>
     public SpdxFile[] Files { get; set; } = [];
 
     /// <summary>
-    ///     Packages
+    ///     SPDX package elements described in this document
     /// </summary>
     /// <remarks>
     ///     Packages referenced in the SPDX document.
     /// </remarks>
     public SpdxPackage[] Packages { get; set; } = [];
 
     /// <summary>
-    ///     Snippets
+    ///     SPDX snippet elements described in this document
     /// </summary>
     /// <remarks>
     ///     All snippet elements described in this SPDX document as defined in SPDX 2.x §5.
@@ -234,6 +249,14 @@ public SpdxDocument DeepCopy()
     /// </remarks>
     /// <param name="issues">List to populate with issues</param>
     /// <param name="ntia">Perform NTIA validation</param>
+    /// <example>
+    ///     <code>
+    ///     var issues = new List&lt;string&gt;();
+    ///     document.Validate(issues, ntia: true);
+    ///     if (issues.Count > 0)
+    ///         Console.WriteLine(string.Join("\n", issues));
+    ///     </code>
+    /// </example>
     public void Validate(List<string> issues, bool ntia = false)
     {
         // Validate SPDX Identifier Field
@@ -336,6 +359,12 @@ public void Validate(List<string> issues, bool ntia = false)
     ///     are unioned.
     /// </remarks>
     /// <returns>Array of packages described by this document</returns>
+    /// <example>
+    ///     <code>
+    ///     foreach (var package in document.GetRootPackages())
+    ///         Console.WriteLine($"{package.Name} {package.Version}");
+    ///     </code>
+    /// </example>
     public SpdxPackage[] GetRootPackages()
     {
         // Get the root packages this document claims to describe (by describes field)

src/DemaConsulting.SpdxModel/Transform/SpdxRelationships.cs

@@ -58,6 +58,19 @@ public static class SpdxRelationships
     ///     neither <c>NOASSERTION</c> nor prefixed with <c>DocumentRef-</c>.
     ///     When this exception is thrown, the document is left unmodified.
     /// </exception>
+    /// <example>
+    ///     <code>
+    ///     SpdxRelationships.Add(document, new[]
+    ///     {
+    ///         new SpdxRelationship
+    ///         {
+    ///             Id = "SPDXRef-DOCUMENT",
+    ///             RelationshipType = SpdxRelationshipType.Describes,
+    ///             RelatedSpdxElement = "SPDXRef-Package"
+    ///         }
+    ///     });
+    ///     </code>
+    /// </example>
     public static void Add(SpdxDocument document, IEnumerable<SpdxRelationship> relationships, bool replace = false)
     {
         // Materialize the enumerable so it can be iterated multiple times