Improve docs

README.md

@@ -213,7 +213,7 @@ loop {
 }
 ```
 
-For a reference OpenGL backend, see [the `egui_glium` painter](https://github.com/emilk/egui/blob/master/egui_glium/src/painter.rs), [the `egui_glow` painter](https://github.com/emilk/egui/blob/master/egui_glow/src/painter.rs), or [the `egui_web` `WebGL` painter](https://github.com/emilk/egui/blob/master/egui_web/src/webgl1.rs).
+For a reference OpenGL backend, see [the `egui_glium` painter](https://github.com/emilk/egui/blob/master/egui_glium/src/painter.rs), [the `egui_glow` painter](https://github.com/emilk/egui/blob/master/egui_glow/src/painter.rs), or [the `egui_web` `WebGL` painter](https://github.com/emilk/egui/blob/master/egui_web/src/webgl2.rs).
 
 ### Debugging your integration
 

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")]

egui/src/containers/panel.rs

@@ -105,7 +105,8 @@ impl SidePanel {
         }
     }
 
-    /// Switch resizable on/off.
+    /// Can panel be resized by dragging the edge of it?
+    ///
     /// Default is `true`.
     pub fn resizable(mut self, resizable: bool) -> Self {
         self.resizable = resizable;
@@ -381,7 +382,8 @@ impl TopBottomPanel {
         }
     }
 
-    /// Switch resizable on/off.
+    /// Can panel be resized by dragging the edge of it?
+    ///
     /// Default is `false`.
     pub fn resizable(mut self, resizable: bool) -> Self {
         self.resizable = resizable;

egui/src/containers/scroll_area.rs

@@ -116,17 +116,21 @@ impl ScrollArea {
         Self::vertical().max_height(max_height)
     }
 
-    /// The desired width of the outer frame of the scroll area.
+    /// The maximum width of the outer frame of the scroll area.
     ///
     /// Use `f32::INFINITY` if you want the scroll area to expand to fit the surrounding `Ui` (default).
+    ///
+    /// See also [`Self::auto_shrink`].
     pub fn max_width(mut self, max_width: f32) -> Self {
         self.max_size.x = max_width;
         self
     }
 
-    /// The desired height of the outer frame of the scroll area.
+    /// The maximum height of the outer frame of the scroll area.
     ///
     /// Use `f32::INFINITY` if you want the scroll area to expand to fit the surrounding `Ui` (default).
+    ///
+    /// See also [`Self::auto_shrink`].
     pub fn max_height(mut self, max_height: f32) -> Self {
         self.max_size.y = max_height;
         self
@@ -185,8 +189,7 @@ impl ScrollArea {
         self
     }
 
-    /// For each enabled axis, should the containing area shrink
-    /// if the content is small?
+    /// For each axis, should the containing area shrink if the content is small?
     ///
     /// If true, egui will add blank space outside the scroll area.
     /// If false, egui will add blank space inside the scroll area.

egui_glium/src/lib.rs

@@ -121,6 +121,7 @@ impl EguiGlium {
         &self.egui_ctx
     }
 
+    /// useful for calling e.g. [`crate::Painter::register_glium_texture`].
     pub fn painter_mut(&mut self) -> &mut crate::Painter {
         &mut self.painter
     }

egui_web/README.md

@@ -16,8 +16,8 @@ Check out [eframe_template](https://github.com/emilk/eframe_template) for an exa
 
 `egui_web` uses WebGL and WASM, and almost nothing else from the web tech stack. This has some benefits, but also produces some challanges and serious downsides.
 
-* Rendering: Getting pixel-perfect rendering right on the web is very difficult, leading to text that is hard to read on low-DPI screens (https://github.com/emilk/egui/issues/516). Additonally, WebGL does not support linear framebuffer blending.
-* Search: you cannot search a egui web page like you would a normal web page.
+* Rendering: Getting pixel-perfect rendering right on the web is very difficult.
+* Search: you cannot search an egui web page like you would a normal web page.
 * Bringing up an on-screen keyboard on mobile: there is no JS function to do this, so `egui_web` fakes it by adding some invisible DOM elements. It doesn't always work.
 * Mobile text editing is not as good as for a normal web app.
 * Accessibility: There is an experimental screen reader for `egui_web`, but it has to be enabled explicitly. There is no JS function to ask "Does the user want a screen reader?" (and there should probably not be such a function, due to user tracking/integrity conserns).

epi/src/lib.rs

@@ -101,7 +101,10 @@ pub use egui; // Re-export for user convenience
 /// and deployed as a web site using the [`egui_web`](https://github.com/emilk/egui/tree/master/egui_web) crate.
 pub trait App {
     /// Called each time the UI needs repainting, which may be many times per second.
+    ///
     /// Put your widgets into a [`egui::SidePanel`], [`egui::TopBottomPanel`], [`egui::CentralPanel`], [`egui::Window`] or [`egui::Area`].
+    ///
+    /// To force a repaint, call either [`egui::Context::request_repaint`] or use [`Frame::repaint_signal`].
     fn update(&mut self, ctx: &egui::CtxRef, frame: &mut Frame<'_>);
 
     /// Called once before the first frame.
@@ -148,7 +151,8 @@ pub trait App {
     // ---------
     // Settings:
 
-    /// The name of your App.
+    /// The name of your App, used for the title bar of native windows
+    /// and the save location of persistence (see [`Self::save`]).
     fn name(&self) -> &str;
 
     /// Time between automatic calls to [`Self::save`]