Fixing a bug in the documentation

Back when I posed the question the other day about 32 bit vs. 64 bit HKLs?, SDiZ properly identified the issue as sign extension, and Igor Tandetnik even pointed out the MSDN article that explains it (search for the "USER and GDI handles are sign extended 32b values" section of the article, which I then quoted in a later comment.

Regular reader Mihai then made an excellent point about the docs  related to the HKL that seem to point in the wrong direction and perhaps lead to confusion here:

Ok, is clear this is cause by signed extension.
But I think is a bug, because the doc says:
"The low word contains a Language Identifier for the input language and the high word contains a device handle to the physical layout of the keyboard"

And this is a bug. Mihai is right. But it is a doc. bug -- a doc. point firmly embedded in the 32-bit world. Though since these handle 'void *' values are signed both managed and unmanaged code will handle them properly, like if you use the following code (which also gives the answer to the other question I asked -- about what the KLID value of an MSKLC-generated keyboard such as "A0000409" might lead to:

System.Int32 i32;
System.Int64 i64;

i32 = -268368865;
i64 = i32;

System.Console.WriteLine(i32.ToString("x") + "\t\t" + i32);
System.Console.WriteLine(i64.ToString("x") + "\t" + i64);

i32 = -1610611703;
i64 = i32;

System.Console.WriteLine(i32.ToString("x") + "\t\t" + i32);
System.Console.WriteLine(i64.ToString("x") + "\t" + i64);

i32 = -536869884;
i64 = i32;

System.Console.WriteLine(i32.ToString("x") + "\t\t" + i32);
System.Console.WriteLine(i64.ToString("x") + "\t" + i64);

This little bit of managed code will output the following:

f001041f                -268368865
fffffffff001041f        -268368865
a0000409                -1610611703
ffffffffa0000409        -1610611703
e0000404                -536869884
ffffffffe0000404        -536869884

As to why I used the decimal version of the numbers rather than the hexidecimal one, it is because managed code is rather unwilling to consider the hex value to be a valid 32-bit signed value, even though once it is assigned it will readily display that value as the hex version. It actually makes dealing with things like the InputLanguage's InputLanguage.Handle property harder to deal with. Best to keep that value opaque and use InputLanguage.Culture.LCID to get that Locale ID if you need it. :-)

But then I started thinking about what one sentence could be used to replace:

"The low word contains a Language Identifier for the input language and the high word contains a device handle to the physical layout of the keyboard"

to handle the reality where we are talking about a bit more than just the high word. Identifying the doc bug is easy, but fixing it is a bit harder in topics like GetKeyboardLayout that contain this bit of boilerplate text.

What would you try and put in there?

This post brought to you by Ḁ (U+1e00, a.k.a. LATIN CAPITAL LETTER A WITH RING BELOW)