CNA-BUG-217: docs/framework-design.md says the Framework.Design registration associates the twelve value types with ordered descriptor collections; registerConverter registers only converter factories

CNA snapshot 009d40f5  ·  Known Issues › Current bugs  ·  source links pinned to 009d40f5

registerConverter registers only a TypeConverterAttribute for each of the twelve math types, while CNA's design note says the registration associates the types with converter factories and ordered descriptor collections. The ordered descriptors exist only inside each converter, so the sentence overstates what the registration does.

Identifier

CNA-BUG-217

Category

Bug

Subsystem

Documentation & release tooling

Status

Open

Verified against

CNA 009d40f5 (009d40f5dd085c4e674d3479675fac84b12b3e0a)

Severity

Low (a triage suggestion, not a project priority)

Evidence basis

Source-verified: read at TARGET, not executed

Tests touching this area

Yes: see Current tests

Affected contract

The registration described in docs/framework-design.md, and System::ComponentModel::TypeDescriptor::GetProperties for the XNA math value types

Expected behaviour

framework-design.md states that linking and using a Design header "pulls a once-only registration translation unit that associates all twelve XNA value types with converter factories and ordered descriptor collections". The design note should describe what the registration actually associates.

Actual behaviour at TARGET

registerConverter<TValue, TConverter>() in Registration.cpp calls TypeDescriptor::RegisterType<TValue> with a single TypeConverterAttribute and leaves the property-collection parameter defaulted, so each type is associated only with a converter factory; the ordered descriptor collections are built by each converter's constructor and are reachable only through the converter's own GetProperties. In the Sharp Runtime revision read alongside TARGET (next at 41b918c9, the last commit before TARGET's date; not pinned by TARGET), TypeDescriptor::GetProperties(const System::Type&) returns only a registered collection, so it is empty for all twelve types. Whether that is a defect is not established: XNA's type-level query reflects public properties only, and most of these types expose their components as public fields (Vector3.X, for example), so an empty answer is not by itself a divergence from XNA. What is established is the documentation overstatement.

Source locations

• modules/design/src/Registration.cpp — registerConverter and EnsureFrameworkDesignConvertersRegistered
• docs/framework-design.md — the Architecture section's registration statement
• modules/design/include/CNA/Internal/Design/Registration.hpp — the inline-variable trigger
• modules/design/tests/Microsoft/Xna/Framework/Design/FrameworkDesignTests.cpp — descriptors are exercised through the converters; no type-level GetProperties query

Evidence

Checked by reading at 009d40f5; nothing was built or executed for this entry. The registration call was read in full; the Sharp Runtime behaviour depends on a sibling revision and was read at 41b918c9 only.

Focused reproduction

Illustrative; not compiled or run for this entry.

#include "Microsoft/Xna/Framework/Design.hpp"
auto viaType = System::ComponentModel::TypeDescriptor::GetProperties(System::Type::From<Microsoft::Xna::Framework::Color>());
// viaType.getCountProperty() == 0 at the Sharp Runtime revision read,
// while ColorConverter's own GetProperties returns the ordered R, G, B, A descriptors.

Current tests

The seventeen converter cases in FrameworkDesignTests.cpp reach descriptors through each converter; none asks TypeDescriptor for a type's properties.

Regression test

Decide the contract. If registration should carry the descriptors, pass the ordered collection to RegisterType and add a test that TypeDescriptor::GetProperties returns the same names in the same order as the converter; otherwise correct the sentence in docs/framework-design.md.

Blast radius

Tools that ask TypeDescriptor rather than the converter for a math type's properties receive an empty collection. Conversion, CreateInstance and the converters' own descriptor lists are unaffected.

Workaround

Query TypeDescriptor::GetConverter for the type and call the converter's GetProperties.