Example Code Comments and Clarity

[MikeFoerster]

I've been trying to develop a project using the M5Stack Core2 and I struggle understanding many of the Example Code. I have recently been trying to move my project from the M5Core2.h to M5Unified and find the same problems with the Examples provided.

I've had similar problems with the examples from the M5Core2 where they would no longer compile (deprecated I2S.h, etc.) but considering that things are moving to the Unified code, I'm trying to address the short comings of the Unified examples. I spent days trying to find a working example of getting a tone out of the speaker output (the example in the M5Unified.h did work!).

I feel that the examples are written by a very experience programmer, that often forgets what it's like to learn how to use the code, and they use all kinds of loops and convoluted code (in my opinion) to demonstrate the functionality and they become very obfuscated. Somethings may not be obvious to those trying to learn how to use those examples. I'm sure that there are those more experience programmers that find these examples usable, but please keep in mind the less experienced. A few lines of comments would go a long way!

Examples:
DragDrop.ino:
https://github.com/m5stack/M5Unified/blob/0.2.3/examples/Basic/Touch/DragDrop/DragDrop.ino
has absolutely no comments to describe the functions or why some of the statements exist, nor are there any Serial.print() statements.

Speaker.ino:
https://github.com/m5stack/M5Unified/blob/0.2.3/examples/Basic/Speaker/Speaker.ino
This example uses some form of a digitized sound (which is included in the code, but missing and not mentioned in the M5Core2 example!). However there is no mention of how that hex code was generated. Is it a .wav file or some other format? How would I generate a file for the sounds that I need?

Microphone.ino:
https://github.com/m5stack/M5Unified/blob/0.2.3/examples/Basic/Microphone/Microphone.ino
There is ONE comment (very useful) but still no indications as to how it works. I can't tell if it's working or not.

I used to be a software test engineer (in a past life), so I'm not exactly a beginner at this, thought I still have a lot to learn and I depend on the examples a great deal.

Mike