Improve docs

eframe/src/lib.rs

@@ -11,11 +11,52 @@
 //!
 //! `eframe` is implemented using [`egui_web`](https://github.com/emilk/egui/tree/master/egui_web) for web and
 //! [`egui_glium`](https://github.com/emilk/egui/tree/master/egui_glium) or [`egui_glow`](https://github.com/emilk/egui/tree/master/egui_glow) for native.
+//!
+//! ## Usage, native:
+//! ``` no_run
+//! use eframe::{epi, egui};
+//!
+//! #[derive(Default)]
+//! struct MyEguiApp {}
+//!
+//! impl epi::App for MyEguiApp {
+//!    fn name(&self) -> &str {
+//!        "My egui App"
+//!    }
+//!
+//!    fn update(&mut self, ctx: &egui::CtxRef, frame: &mut epi::Frame<'_>) {
+//!        egui::CentralPanel::default().show(ctx, |ui| {
+//!            ui.heading("Hello World!");
+//!        });
+//!    }
+//!}
+//!
+//! fn main() {
+//!     let app = MyEguiApp::default();
+//!     let native_options = eframe::NativeOptions::default();
+//!     eframe::run_native(Box::new(app), native_options);
+//! }
+//! ```
+//!
+//! ## Usage, web:
+//! ``` no_run
+//! #[cfg(target_arch = "wasm32")]
+//! use wasm_bindgen::prelude::*;
+//!
+//! /// Call this once from the HTML.
+//! #[cfg(target_arch = "wasm32")]
+//! #[wasm_bindgen]
+//! pub fn start(canvas_id: &str) -> Result<(), eframe::wasm_bindgen::JsValue> {
+//!     let app = MyEguiApp::default();
+//!     eframe::start_web(canvas_id, Box::new(app))
+//! }
+//! ```
 
 // Forbid warnings in release builds:
 #![cfg_attr(not(debug_assertions), deny(warnings))]
 #![forbid(unsafe_code)]
 #![warn(clippy::all, missing_crate_level_docs, missing_docs, rust_2018_idioms)]
+#![allow(clippy::needless_doctest_main)]
 
 pub use {egui, epi};
 
@@ -35,7 +76,16 @@ pub use egui_web::wasm_bindgen;
 /// fill the whole width of the browser.
 /// This can be changed by overriding [`epi::Frame::max_size_points`].
 ///
-/// Usage:
+/// ### Usage, native:
+/// ``` no_run
+/// fn main() {
+///     let app = MyEguiApp::default();
+///     let native_options = eframe::NativeOptions::default();
+///     eframe::run_native(Box::new(app), native_options);
+/// }
+/// ```
+///
+/// ### Web
 /// ``` no_run
 /// #[cfg(target_arch = "wasm32")]
 /// use wasm_bindgen::prelude::*;
@@ -60,14 +110,45 @@ pub fn start_web(canvas_id: &str, app: Box<dyn epi::App>) -> Result<(), wasm_bin
 // ----------------------------------------------------------------------------
 // When compiling natively
 
-/// Call from `fn main` like this: `eframe::run_native(Box::new(MyEguiApp::default()))`
+/// Call from `fn main` like this: `
+/// ``` no_run
+/// use eframe::{epi, egui};
+///
+/// #[derive(Default)]
+/// struct MyEguiApp {}
+///
+/// impl epi::App for MyEguiApp {
+///    fn name(&self) -> &str {
+///        "My egui App"
+///    }
+///
+///    fn update(&mut self, ctx: &egui::CtxRef, frame: &mut epi::Frame<'_>) {
+///        egui::CentralPanel::default().show(ctx, |ui| {
+///            ui.heading("Hello World!");
+///        });
+///    }
+///}
+///
+/// fn main() {
+///     let app = MyEguiApp::default();
+///     let native_options = eframe::NativeOptions::default();
+///     eframe::run_native(Box::new(app), native_options);
+/// }
+/// ```
 #[cfg(not(target_arch = "wasm32"))]
 #[cfg(feature = "egui_glium")]
 pub fn run_native(app: Box<dyn epi::App>, native_options: epi::NativeOptions) -> ! {
     egui_glium::run(app, &native_options)
 }
 
-/// Call from `fn main` like this: `eframe::run_native(Box::new(MyEguiApp::default()))`
+/// Call from `fn main` like this: `
+/// ``` no_run
+/// fn main() {
+///     let app = MyEguiApp::default();
+///     let native_options = eframe::NativeOptions::default();
+///     eframe::run_native(Box::new(app), native_options);
+/// }
+/// ```
 #[cfg(not(target_arch = "wasm32"))]
 #[cfg(not(feature = "egui_glium"))] // make sure we still compile with `--all-features`
 #[cfg(feature = "egui_glow")]