Clarifications needed for CMAKE_<LANG>_LINKER_PREFERENCE* variables

The docs for CMAKE_<LANG>_LINKER_PREFERENCE_PROPAGATES don’t state whether CMake sets this variable and expects it to be read-only, or whether it is intended to be set by the project to indicate it’s preference. Another possibility is that CMake sets it as part of enabling languages (which appears to be the case, at least for some languages) but the project is allowed to change it. What is the expectation for this variable?

Similar situation for CMAKE_<LANG>_LINKER_PREFERENCE too, it is unclear from the docs whether projects should be allowed to change this. Looking at what this variable does, it seems likely the variable should be considered read-only, except perhaps from inside a toolchain file. Furthermore, its docs contain the following statement:

Otherwise, the linker language is that whose linker preference value is highest among languages compiled and linked into the target.

But in the docs for CMAKE_<LANG>_LINKER_PREFERENCE_PROPAGATES, it has this sentence:

A language compiled into static libraries linked by the target is considered if this variable is true.

The statement in the docs for CMAKE_<LANG>_LINKER_PREFERENCE doesn’t tell the whole story, it only cross-references CMAKE_<LANG>_LINKER_PREFERENCE_PROPAGATES but doesn’t make the reader aware that propagation for linked static libraries depends on CMAKE_<LANG>_LINKER_PREFERENCE_PROPAGATES. Am I missing something, or is this just a deficiency in the docs?

These variables are all generator implementation details not meant to be set by project code at all. I don’t know why they’re even documented.

It may have been because the public LINKER_LANGUAGE target property refers to them when mentioning linker preference. Anyway, I’ll move the two internal variables in the variable index and add a note to them both to make clear they are internal variables.