Remove some examples which are adequately covered by documentation

[jessebraham]

Some progress towards #2513. If anybody disagrees that the documentation is an adequate replacement for these examples please let me know and I will make the necessary updates.

Will continue looking for more example to remove.

[elrom]

Just saw this after the examples were removed. I disagree. e.g. googling "enable_pin_with_cal" now results in not a single decent example.

[brainstorm]

Also disagree: will those examples in docs still get as good test coverage as those in the examples repo directory?

[bugadani]

Keep in mind that our goal is not to take away information, but to make it possible for us to maintain example snippets with reasonable effort. Updating 100+ examples multiple times in a development cycle is not reasonable.

Feel free to list any specifics that you are no longer able to find.

[brainstorm]

Keep in mind that our goal is not to take away information, but to make it possible for us to maintain example snippets with reasonable effort. Updating 100+ examples multiple times in a development cycle is not reasonable.

Feel free to list any specifics that you are no longer able to find.

Fair point, I didn't consider that angle... Mine was just a general observation from experience: I just find well maintained examples invaluable for quick iteration and extremely frustrating when I have to delve into docs (which invariably have higher bitrot rate) only to realise that API has drifted and need to tweak accordingly, spending time where I shouldn't when resolving a task.

[jessebraham]

Also disagree, I guess that those simple examples will not get proper test coverage once they are in the docs vs the actual source tree?

Examples are not tests. We have hardware-in-loop testing, we have doctests that we build in CI. What specifically do you feel is lost by the removal of these specific examples? The sheer number of examples are a huge burden to the maintainers as it stands.

[brainstorm]

Again, no specifics here, just principles from experience: All I'm saying is that as long as the doc examples are copy-pastable and work "out of the box" right away on each release, culling would be just fine. Otherwise you'd be trading UX for DX... one specific thing I'm missing is matching Cargo.toml, .cargo/config.toml configs in the docs which can be tricky to handle well and rustc errors can be cryptic and unhelpful for misplaced flags.

If there's bitrot in the examples from docs, more support requests and issues might arise as a result from users: what's harder to maintain from de core dev side then, keeping all examples runnable or fielding support requests?

Current mood in this post and all of the above from me: agreeable (text comms can get hot for no good reason) ;)