docs: full documentation audit — accuracy fixes, XML docs, planned-package framing

[brenpike]

Summary

A full audit of the repository's user-facing documentation — README, docs/**, CLAUDE.md, and public XML doc comments — checked against the actual source, with every defect found corrected. No product behavior changes.

What was wrong

Examples that would not compile

• README.md called .AddLinks(), which does not exist anywhere in the builder API.
• README.md, docs/api.md, and docs/serialization.md referenced a Chatter.Rest.Hal.Extensions namespace. No such namespace exists — every extension class declares namespace Chatter.Rest.Hal.
• Builder snippets in README.md and docs/usage.md were missing using Chatter.Rest.Hal.Builders;.
• docs/usage.md looked up a link object by name against an example that only ever set Title, so the documented lookup could never match.

Documented behavior that contradicted the code

• The README.md dynamic example's "resulting JSON" predated the 2.0.0 curies change: curies serializes as an array even for a single definition (_isArray = rel == CuriesLink), and the example's ea:admin relation holds two link objects, not one. The block was regenerated from real serializer output.
• AddHalConverters idempotency was described as a whole-batch bail-out in three documents. It is a per-converter AddIfMissing guard: a consumer with a subset pre-registered gets only the missing converters, and pre-registered converters keep their own HalJsonOptions.
• docs/architecture.md's converter constructor table did not match the real constructors.
• ResourceConverter's read/write description was wrong in docs/architecture.md and docs/serialization.md.
• GetLinkOrDefault (SingleOrDefault, throws on duplicate relations) and the two GetLinkObjectOrDefault overloads (by relation is FirstOrDefault; by name is SingleOrDefault) had their contracts undocumented or misstated. That asymmetry is now explicit.
• AddResource() vs AddResources() return-target semantics were conflated in both the stage XML docs and docs/api.md.
• docs/development.md claimed "There is no global.json in this repository." There is one, pinning SDK 8.0.100 with rollForward: latestMinor. Target-framework claims were also wrong: Chatter.Rest.Hal.CodeGenerators is netstandard2.0-only.

Stale and dead content

• docs/architecture.md referenced package version 1.1.0 in several places.
• Two dead links to docs/uri-templates/* — Chatter.Rest.UriTemplates is an external NuGet dependency with no in-repo docs.

Missing coverage

• Relation merging (LinkCollectionBuilder merges repeated AddLink/AddSelf/AddCuries via GetOrAddLink) and the curies array default were undocumented.
• The duplicate-key contract was undocumented: LinkCollection.Add and EmbeddedResourceCollection.Add throw ArgumentException, while deserialization normalizes duplicates last-wins.
• 22 public types carried zero XML doc comments — all 20 fluent builder stage interfaces plus HalResponseAttribute and HalResponseGenerator. Since the builder's whole discoverability story is IntelliSense on the next stage, this was the largest gap in the audit. The new comments follow the two already-documented sibling stage files.

Framing

• docs/aspnetcore/* described Chatter.Rest.Hal.AspNetCore in shipped present tense, but no such project exists and nothing is published. Both documents now carry a status banner marking them design specs for a planned package, and the CLAUDE.md documentation index says so too. The design content itself is unchanged; only the tense and the banner. Resource<T> is annotated as a planned core addition rather than deleted.

Review remediation

Codex raised one P1 on the initial push, and it was correct: the release advertised new XML documentation comments, but neither packable csproj set GenerateDocumentationFile, so no XML sidecar was produced or packed. Consumers of the published package would have gotten no IntelliSense from any of the 22 newly documented types — the documentation existed only in source.

Fixed in 285bd84 and 10acd3a:

• src/Chatter.Rest.Hal/Chatter.Rest.Hal.csproj sets GenerateDocumentationFile=true. A packed .nupkg was inspected and contains both lib/net8.0/Chatter.Rest.Hal.xml and lib/netstandard2.0/Chatter.Rest.Hal.xml.
• Enabling generation exposed latent doc defects that were previously invisible, all now repaired. Six unclosed </remarks> blocks in each of IEmbeddedLinkObjectPropertiesSelectionStage.cs and IResourceLinkObjectPropertiesSelectionStage.cs — the malformation had been causing the compiler to silently discard the surrounding comments — plus interface summaries and AsArray() documentation for both. Two unresolvable JsonNode.Deserialize crefs (ConverterHelpers.cs, ResourceConverter.cs) replaced with JsonSerializer.Deserialize{TValue}(JsonNode, JsonSerializerOptions). Two ambiguous State{T} crefs in Resource.cs closed to State{T}(JsonSerializerOptions?), the overload that actually holds the Link-guard the surrounding prose describes.
• CHANGELOG.md [2.1.1] extended to state the packed sidecar and the doc repairs.

The build now emits zero documentation warnings of any code (CS1570, CS1574, CS1591, CS0419 all clear). Beyond fixing the reported symptom, this closes the class: with generation enabled the compiler surfaces missing or malformed doc comments on every build, so "documented in source, invisible to consumers" cannot silently recur for this package.

Deliberately not applied to Chatter.Rest.Hal.CodeGenerators. That package sets IncludeBuildOutput=false and packs its assembly only into analyzers/dotnet/cs, which consumer code never references — an XML sidecar there would be unreachable by any consumer's IDE. Its consumer-facing surface is the emitted HalResponseAttribute.g.cs, and AttributeSource.cs already embeds doc comments in that emitted source, so [HalResponse] IntelliSense already works.

No further version bump: 2.1.1 is unpublished until merge, so the sidecar ships with that release.

Versioning

Chatter.Rest.Hal 2.1.0 → 2.1.1, Chatter.Rest.Hal.CodeGenerators 0.4.0 → 0.4.1, with CHANGELOG entries.

These are PATCH bumps for a change that alters no API and no behavior. They are required mechanically: version-check.yml fires on any non-markdown change under a package's src path, XML doc comments are .cs edits, and tags hal/v2.1.0 and codegen/v0.4.0 already match the prior versions, so the check would fail without a bump.

The 2.1.1 bump additionally covers the packaging change above — the package now ships an XML documentation file it did not ship before.

Validation

• dotnet build Chatter.Rest.Hal.sln -c Release — succeeded, 0 errors, 0 documentation warnings. The 3 remaining CS8604 warnings are pre-existing nullability warnings, untouched.
• dotnet test -c Release — 507/507 passed (456 HAL, 51 CodeGenerators).
• dotnet pack output inspected to confirm the XML sidecar is present for both target frameworks.
• Local pre-PR review converged clean over 5 iterations; post-remediation GitHub review pass is clean with the P1 thread resolved.

Follow-ups (not in this PR)

1. Stale pin. Chatter.Rest.Hal.CodeGenerators.csproj references Chatter.Rest.Hal at 1.1.0. Left untouched because changing it is a build change, not a documentation fix, and warrants its own validation.
2. Pre-existing nullability warnings. 3 CS8604 warnings predating this branch: Converters/LinkConverter.cs:122 and test/Chatter.Rest.Hal.Tests/Converters/ConverterWriteAndRegistrationCleanupTests.cs:188,208. Executable-code changes, outside a documentation PR.
3. Unaudited documents. docs/backlog.md, docs/consistency-audit.md, docs/performance-todo.md, docs/client/, docs/mcp/, CONTRIBUTING.md, CONTEXT-MAP.md, and the per-project CONTEXT.md files were outside this audit's scope. Mostly internal working docs rather than the user-facing surface, but available as a follow-up pass.
4. docs/development.md §8 claims netstandard2.0 nullable warnings originate in converter files. Plausible but unverified — a product-code claim rather than a documentation defect, so it was left alone.

The originally-listed follow-up covering pre-existing XML documentation warnings (CS1570 / CS1574) is now resolved in this PR — enabling documentation generation required absorbing that tail rather than deferring it.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c74805baf4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".