Added a couple "to be documented" items

[Jennigma]

I added a couple items to the list of things that should be documented.

I also realize I have no idea what the ANY key does, but I'm intrigued. I don't understand from these code comments, and don't have time to puzzle it out now.

Otherwise, though, this is so much better than the file I've been poking at for weeks! It's clear and clean and much more welcoming. Thanks for all the behind the scenes work that made this possible, and thank you Jesse for the work writing up comments!

[obra]

Thanks!

[algernon]

FWIW, when you press the Any key, it will input a random alphanumeric symbol on each press. That is, if you press Any, it may input a first, but when you press it again, it might input 6. It will not change which symbol is input while held, only on key press.

Does that make its intent clearer?

(There is some explanation about it here, which I find clear, but I'm not a good metric when it comes to documentation :))

[Jennigma]

rvuik0qurf930mkg7i0grfdrdeeakifq6n1bj4ca9cfu291g9zy39uo34vrb38l4n8uapzr

I see! theoretically "any" key. amusing. Why does it generate only lowercase letters and numerals?

Also, the holding it down part doesn't work for me. If it's a vowel OSX offers me accenting options, otherwise nothing happens.

I just took a boondoggle and learned what a uint8_t is, so that was fun. ;-)

[algernon]

Why does it generate only lowercase letters and numerals?

Because it simulates a single key being pressed, and uppercase would require a shift, too. You can press Shift+Any to get uppercase stuff, though.

Also, the holding it down part doesn't work for me. If it's a vowel OSX offers me accenting options, otherwise nothing happens.

Does the same thing happen when you hold down a normal vowel key?

[Jennigma]

Does the same thing happen when you hold down a normal vowel key?

Yes, apologies, should have clarified. That's normal behavior for OSX, which I appreciate regularly. since one of my friends is named Jørgen. :-)

Because it simulates a single key being pressed, and uppercase would require a shift, too. You can press Shift+Any to get uppercase stuff, though.

Figured out the shift thing. I more wondered why there weren't punctuation marks and other "keys" getting randomized into the mix. why only alphanumeric?

[obra]

On Oct 4, 2017, at 4:46 PM, Jennifer Leigh notifications@github.com wrote:

why only alphanumeric?

It felt right to me. I’m not strongly attached to that, though.

[algernon]

Figured out the shift thing. I more wondered why there weren't punctuation marks and other "keys" getting randomized into the mix. why only alphanumeric?

Practical reasons: alphanumerics are a single, continous block of key codes, punctuation and other keys have keycodes furher away. (See key_defs_keyboard.h - the order of keys there corresponds to their keycode for the most part). To include those in the mix too, we'd need to filter out unwanted things (like Enter, Escape, and others), and while that would not be too hard, it would make the macro a lot more complicated. Keeping it simple hopefully makes it easier for people to understand what it does, learn from it, tweak it, and so on.

It is a compromise between something funny, and something educational.

[Jennigma]

why only alphanumeric?

It felt right to me. I’m not strongly attached to that, though.

Apologies for being imprecise with my "why". I get why alphanumerics are preferred, but don't understand how the code is restricted to generating those. I expect the answer would come to me if I traced my way through the function in detail, and it's not something I want to spend cycles on now. :-)

I have an hour between things right now, and am going to go work through your new install process.

[algernon]

Ah, that "why"!

lastKey.keyCode = Key_A.keyCode + (uint8_t)(millis() % 36);

This is where the trick lies: the keycode we send will be chosen by looking at the time, and making sure we get at most 35 (the % 36 thing means we divide the previous number by 36, and look at the remainders, so it will be a number between 0 and 35). Then we add the keycode of the a key to it, so if our chosen number is 0, we'll get a. There are 26 letters in the English alphabet, and we have 10 digits, that's how that 36 was chosen. As the alpha keycodes are immediately followed by the numerics, we can chose from these 36 keys easily.

There are multiple things in play here:

• Alphas are followed by numerics, so they form a single block of codes we can choose from.
• We can use the remainder of the current time divided by the amount of codes we want to restrict random numbers to a range between 0 and 36 (number of alphas + numerics).
• Because keycodes are numbers, we can just add the keycode of a to our results, to shift the scale, so to say.

Hope this helps!

[Jennigma]

@algernon got it!