Chapter 76 Auditing xna4-spec Compatibility

At pinned commit 8f61207, the top-level index references 544 XML type files across 19 documented namespaces. Each file records a kind, syntax, members, overloads, parameters, return text, remarks, and links derived from the former Microsoft documentation archive. The collection includes runtime namespaces and the content-pipeline namespaces CNA does not aim to implement.

The README’s example tree says “550 types,” while its coverage table, index, plan numbering, and files all say 544. This small internal drift is the first rule of using the corpus: treat even a machine-readable conversion as data to validate, not as an infallible executable specification. The repository’s disclaimer also makes clear that the converted documentation remains Microsoft’s content and is offered for informational and educational use.

No file in CNA references xna4-spec. CNA’s current port checklist instead names the XNA reference-assembly XML as the authority for API surface and FNA as the reference for behavior. Real XNA execution, FNA differential values, and image oracles then settle questions documentation cannot.

xna4-spec is therefore a convenient complementary inventory. It can expose a missing property that FNA itself omitted, supply remarks for manual review, and make namespace-wide audits scriptable. It cannot prove CNA behavior, and a clean comparison against it is not an existing CNA gate. A book or report must not promote an offline sibling repository into a runtime authority merely because its name contains “spec.”

For one type, a disciplined comparison has six steps:

1. 1.

   pin the xna4-spec, CNA, FNA, and reference-assembly revisions;

2. 2.

   extract fields, properties, constructors, methods, events, and overload signatures from the XML rather than counting prose mentions;

3. 3.

   map C# idioms explicitly: properties to getter/setter names, operators to C++ operators, ref/out to reference overloads, and iterators to CNAEXT;

4. 4.

   compare CNA’s public header and classify each row as exact surface, accepted language adaptation, marked extension, unexplained extra, or missing;

5. 5.

   read remarks and implementation for every hand-written accessor or behavior-bearing method;

6. 6.

   attach an executable oracle for semantics and record cases the XML cannot decide.

The mapping table is part of the result. Otherwise Equals(object) looks like a missing member even though a C++ value type has no universal boxed root, and a default constructor or iterator can look like an unmarked XNA extension even when it exists only for the target language’s ordinary value/container idiom.

Microsoft.Xna.Framework/Ray.xml describes the Position and Direction fields, the two-vector constructor, equality, hash and string methods, intersection overloads, and equality operators. CNA’s modules/math/.../Ray.hpp contains both fields, the constructor, value equality, ToString, four intersection target types, output-reference forms for box, sphere and plane, and free equality operators.

The comparison also exposes adaptations. CNA adds a default constructor, omits boxed Equals(Object), and returns std::size_t from GetHashCode rather than C# int. Those choices match CNA’s documented C++ conventions; they should be classified, not silently counted as either perfect matches or defects.

The converted XML itself needs normalization. Its Intersects list contains duplicate output overload records, and some signatures are labelled with the wrong target type even though the surrounding parameter text names Plane or BoundingSphere. A script that compares signature strings blindly will invent duplicates and gaps. Cross-checking the reference-assembly member IDs or the original documentation is necessary whenever converted fields disagree.

The Viewport XML lists two non-default constructors, nine properties, and Project, Unproject, and ToString. CNA’s header provides those members through a mix of generated field properties and hand-written accessors. It also has a default constructor that produces zero width/height and a 0-to-1 depth range.

The surface comparison looks strong, but TitleSafeArea demonstrates why surface is not semantics. CNA returns Bounds unchanged and pins that choice with TitleSafeAreaEqualsBounds. The documentation describes a subset guaranteed visible on lower-quality displays. A passing test proves CNA’s chosen behavior is stable; it does not prove the choice matches XNA on every platform.

The right outcome is a recorded behavioral deviation or a real-XNA experiment, not a surface- coverage percentage. Hand-written properties deserve particular scrutiny because computation and policy can hide behind a signature that compares perfectly.

An XML API inventory cannot establish default values produced by a runtime, floating-point edge behavior, exception type and timing, lifetime, GPU state, wire compatibility, content decoding, or platform substitution. It also cannot tell whether a nominally present method is a stub, a safe refusal, or a complete implementation.

Use xna4-spec to generate questions and completeness rows. Use CNA’s compile-time CNAEXT gate to detect unmarked additions, reference assemblies to settle surface, FNA or real XNA to settle semantics, and the oracle hierarchy from Chapter 70 to produce verdicts. The most trustworthy audit is not the one with the highest percentage, but the one that preserves these authorities instead of collapsing them into one number.