Framework documentation

[John-Nagle]

CF wrote on Discord: "Besides documentation, which those components are in dire need of, is there anything that would help those make more sense?".

I wrote: For Rust, if you put all the Rustdoc comments in the expected places, you get reasonable documentation of things that someone calls. That doesn't work for frameworks.

What seems to be needed for a framework is a detailed, accurate description of all the stuff you have to provide to make it work. For the Rend3 system, there are a lot of moving parts - the window, the platform, the context, the renderer, and the app instance. Some explanation of what they do, how long they live, who owns what, and what can be shared or copied would be useful. In a framework, you don't own; you are owned. You need to know the rules imposed by your owner.

So, here are some concrete remarks.

For the Rend3 framework, there are two main callbacks: setup and handle_event.

• A large number of very specific things must be done in setup, and there is little documentation on this. Users must copy and paste from the examples and try to fix what results.

• The handle_event callback calls the user code for each window event. The Rend3_framework::Event::RedrawRequested(..) again requires that the user do a large number of very specific and obscure things. The things that need to be done changed in the last refactoring.

Those are the two spots that most need documentation. Coding with frameworks is prone to errors of omission. This is ritual-taboo programming. The framework user must know the proper incantations, even if they are not required to understand them.

I'm puzzling this out by reading the diffs to the egui example:
Refactor rend3 to use Vertex Pulling (#449) · BVE-Reborn/rend3@0fa5...
I have only a vague idea of what I'm doing in that area.

As for code changes, the only thing I'd suggest right now is having setup, handle_event, and start all support returns of the form Result<(), anyhow::Error>. There are many things that can go wrong in graphics setup, and if you fail an "unwrap()" in a GUI program, the user experience is that the program exits with no explanation. Calls in setup and handle_event should be able to use "?" to handle errors. The start call that runs the framework should return a Result, so the calling program has a single place to handle major trouble.

GUI programs usually need to bring up an emergency panic dialog and perhaps phone home to a server on failure. I use this, which is cross-platform, for panic-level errors.

/// We're in real trouble and the main GUI isn't running. Modal dialog.
pub fn panic_dialog(title: &str, message: &str) {
    //  Serious errors only. Only use when the main GUI is unavailable at startup
    let _ = rfd::MessageDialog::new()
        .set_title(title)
        .set_description(message)
        .set_buttons(rfd::MessageButtons::Ok)
        .set_level(rfd::MessageLevel::Error)
        .show();
}

This is not high priority, but may improve adoption of Rend3.