CNA-BUG-242: Source comments still say StorageDevice reaches the platform or the SDL preference path

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

IPlatformFileSystem::GetPreferencesPath is documented as backing StorageDevice and several comments cite storage as a reason for the ambient platform, but storage has no platform dependency and GetPreferencesPath has no production caller.

Identifier

CNA-BUG-242

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

Doxygen of CNA::Platform::IPlatformFileSystem::GetPreferencesPath, CNA::Platform::GetCurrentPlatform, Game::GetPlatformEXT, the X11 and Wayland platform constructors, and the CApi_StorageSmoke registration comment

Expected behaviour

storage/CMakeLists.txt: "Storage owns its portable save-root policy. It intentionally does not depend on the platform module", and the probe_storage link-closure test in ModuleProbes.cmake enforces it. Comments elsewhere should say the same.

Actual behaviour at TARGET

IPlatformSystemServices.hpp documents GetPreferencesPath as "Backs StorageDevice", yet nothing outside the three platform implementations calls it. CurrentPlatform.hpp lists StorageDevice among the static XNA APIs that need the ambient platform and says the lazy default "keeps a bare StorageDevice call working"; Game::GetPlatformEXT's documentation, the X11 platform constructor and the Wayland platform class say a platform must exist for StorageDevice; the CApi_StorageSmoke registration says "The storage root is derived from the platform preference path"; a storage test comment reasons about "a SDL pref-path directory". StorageDevice.cpp resolves its root from XDG_DATA_HOME, LOCALAPPDATA, HOME or the working directory and includes no platform header.

Source locations

• modules/platform/include/CNA/Platform/IPlatformSystemServices.hpp — IPlatformFileSystem::GetPreferencesPath documented as backing StorageDevice
• modules/platform/include/CNA/Platform/CurrentPlatform.hpp — GetCurrentPlatform documentation names StorageDevice
• modules/runtime/include/Microsoft/Xna/Framework/Game.hpp — GetPlatformEXT documentation names StorageDevice
• modules/platform/src/X11/X11Platform.hpp — constructor documentation: a platform is constructed to reach StorageDevice
• modules/platform/src/Wayland/WaylandPlatform.hpp — class documentation: StorageDevice needs a platform
• modules/c-api/CMakeLists.txt — CApi_StorageSmoke comment about the platform preference path
• modules/storage/CMakeLists.txt — storage deliberately has no platform dependency
• modules/storage/src/StorageDevice.cpp — StorageDevice::EnsureStorageRoot resolves the root from the environment

Evidence

Checked by reading the files above at 009d40f5, and a search of the TARGET tree for GetPreferencesPath (the interface, its SDL3, Win32 and portable implementations, and platform tests only); not executed. The same comments also name TitleContainer; whether that half is still true was not re-checked and is not part of this entry. The storage internals page lists these comments. The storage-test comment is also cited by CNA-BUG-201.

Focused reproduction

# Shown for reference: the stale statements and the missing callers.
grep -rn "StorageDevice" modules/platform/include modules/platform/src/X11/X11Platform.hpp \
    modules/platform/src/Wayland/WaylandPlatform.hpp modules/runtime/include/Microsoft/Xna/Framework/Game.hpp
grep -rn "GetPreferencesPath" modules --include=*.cpp | grep -v "modules/platform/"

Current tests

ModuleProbe_probe_storage and ModuleLinkClosure_probe_storage enforce the absence of the platform edge; nothing checks comments against it.

Regression test

Remove StorageDevice from those comments (keeping TitleContainer where it remains true) and either give GetPreferencesPath a caller or document it as an unused service.

Blast radius

Maintainers only: a reader of the platform headers would look for storage behaviour in the platform module, or keep an unused service alive for storage's sake. No runtime effect.

Workaround

Trust storage/CMakeLists.txt, StorageDevice.cpp and the link-closure probe over these comments.