More Description in Example Documentation

[pearson]

The documentation for examples could use to be expanded with more description of the code to help those who are new to Zephyr.

As an example, take the second in the "Classic" examples, "Synchronization":

• Why does it do a k_busy_wait followed by a k_msleep before releasing the semaphore?
• Why are there three ARG_UNUSED dummy variables at the start of each thread function?
• What is the PIN_THREADS define used for, and the k_thread_cpu_mask_clear and k_thread_cpu_mask_enable calls it enables?

For someone new to Zephyr (such as myself), there are many questions that could be answered in an example's documentation rather than through searching the entire set of documentation. Getting up to speed quickly, rather than having to read through more material than is currently needed, can be very useful.