Examples are the best documentation

Even better if the documentation examples are part of the test suite!

Right, one of the best out-of-box tooling decisions for Rust is that by default, and out of the box cargo will assume all your documentation examples are tests it should compile and execute.

This means so long as you run the tests before shipping you basically can't ship with examples you forgot to update after an API change because they either don't compile or don't work.

And you might think well, nobody would ship examples that don't even compile right? But on more than one occasions I've used a Microsoft C# library that comes with examples clearly hand made by their engineers (yes I'm that old that it couldn't be LLM output) without checking they work. Somebody has sketched out what ought to work, they haven't tested it, and a reviewer has seen that it looks right and OK'd it, but again, never tested that it works. This is extremely frustrating because the documentation is wrong but now what?

i have at times looked at tests to get an idea of how the developer expected the code to be used.

I'd go a bit further and say that all tests are documentation examples. Rust is nice because it has symmetry and documentation examples are tests.

The dlang website generator does not succeed unless all the coding examples run successfully.