search

esp-rs / esp-hal

no_std Hardware Abstraction Layers for ESP32 microcontrollers
https://docs.esp-rs.org/esp-hal/
Apache License 2.0
769 stars 214 forks source link

Remove some examples which are adequately covered by documentation #2538

Closed jessebraham closed 1 week ago

jessebraham commented 1 week ago

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 commented 1 week ago

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 commented 1 week ago

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

bugadani commented 1 week ago

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 commented 1 week ago

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 commented 1 week ago

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 commented 1 week ago

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) ;)