Picking this 16739 comment into generalization, let’s think about what purposes examples serve:
Demos. Users flash this, and can right away explore what RIOT can do, play with it, learn the high-level concepts and verify their understanding of what their hardware can do.
Examples: filesystem, gcoap, saul, nimble_heart_rate_sensor
Utilities: Similar to demos, but with the additional expectation that you’d just flash them and start using them in almost a productive setup.
Examples: gnrc_border_router, maybe ccn-lite-relay
Scaffolding to start own applications: You can flash this, but usually you’d start editing there until you’re fed up with the “helloworld” name and copy what by now has become an own project of yours into a separate folder.
Examples: gcoap (esp. server side), hello-world, usbus_minimal
Illustrations of concrete APIs and how to use them.
Examples: the TCP Echo server of the abovementioned issue, dtls-echo, timer_periodic_wakeup
Build and hardware testing:
Examples: everything in test
The reason I’m pulling test in here is that time and again when trying to understand an API I grep to the examples, find nothing, but the tests work perfectly fine to serve the “Illustration of a concrete API” case.
So far, I don’t have a point to make, but more of an open question:
Is the line currently drawn between tests and examples the right one? Do API examples water down the more read-to-start examples? Did we see feedback from newcomers who try to navigate the examples?