You can in theory turn off gc but in practice no one does this because nearly everything is written with the assumption that allocations will be cleaned up by the gc. The compiler has no switches to help you run in a non-gc’d state. At best you can control when you run the gc.
Some of the best technical documentation I’ve ever written has straight up lies in it. Granted they were placed there in the service of distilling the most germane portions of the API I was trying to explain. But it made a huge difference once I decided my code in the library didn’t have to be my code in its documentation. I felt a little like a biographical writer who makes a composite character. But honestly I recommend trying it. Lie in your docs if it serves the greater goal of communicating what’s most important. Let the computer labor in the “truth” and its tediums.
Do you mean you just left out required args, try-catches for checked exceptions, and so on, so the example would be easier to read? Did you put an asterisk on, like "* illustrative code: will not compile"?
I think the test is for this is whether the project is willing to break with the past to _keep_ the api simple, clean, and fast. You're right that is easier for new projects who have no backward compatibility to speak of. From what I've seen bevy has a strong culture of demanding good ergonomics for the users and reducing the api surface, and maybe it's thanks to rust's packaging, but they're very willing to break with the past to get it, which I appreciate.
The nice thing too is with cargo, should you ever commit to bevy, they can break the future, and you don't have to chase a moving target. You can just stick to your version. But they also provide guides to make moving up to the latest and greatest easy. Or at least that's been my experience as a bevy dabbler.
