Add misc documentation

.github/ISSUE_TEMPLATE/bug_report.md

@@ -20,7 +20,7 @@ eframe = { git = "https://github.com/emilk/egui", branch = "master" }
 -->
 
 **Describe the bug**
-<!-- A clear and concise description of what the bug is. -->
+<!-- A clear and concise description of what the bug is. An image is good, a gif or movie is better! -->
 
 **To Reproduce**
 Steps to reproduce the behavior:

CONTRIBUTING.md

@@ -16,7 +16,7 @@ There is an `egui` discord at <https://discord.gg/vbuv9Xan65>.
 
 ## Filing an issue
 
-[Issues](https://github.com/emilk/egui/issues) are for bug reports and feature requests. Issues are not for asking questions (use [Discussions](https://github.com/emilk/egui/discussions) for that).
+[Issues](https://github.com/emilk/egui/issues) are for bug reports and feature requests. Issues are not for asking questions (use [Discussions](https://github.com/emilk/egui/discussions) or [Discord](https://discord.gg/vbuv9Xan65) for that).
 
 Always make sure there is not already a similar issue to the one you are creating.
 
@@ -36,6 +36,8 @@ When you feel the PR is ready to go, do a self-review of the code, and then open
 
 Please keep pull requests small and focused.
 
+Don't worry about having many small commits in the PR - they will be squashed to one commit once merged.
+
 Do not include the `.js` and `.wasm` build artifacts generated for building for web.
 `git` is not great at storing large files like these, so we only commit a new web demo after a new egui release.
 
@@ -59,6 +61,7 @@ While using an immediate mode gui is simple, implementing one is a lot more tric
 
 * read some code before writing your own
 * follow the `egui` code style
+* add blank lines around all `fn`, `struct`, `enum`, etc.
 * write idiomatic rust
 * avoid `unsafe`
 * avoid code that can cause panics

egui/src/memory.rs

@@ -19,7 +19,15 @@ use crate::{area, window, Id, IdMap, InputState, LayerId, Pos2, Rect, Style};
 pub struct Memory {
     pub options: Options,
 
-    /// This map stores current states for all widgets with custom `Id`s.
+    /// This map stores some superficial state for all widgets with custom `Id`s.
+    ///
+    /// This includes storing if a [`crate::CollapsingHeader`] is open, how far scrolled a
+    /// [`crate::ScrollArea`] is, where the cursor in a [`crate::TextEdit`] is, etc.
+    ///
+    /// This is NOT meant to store any important data. Store that in your own structures!
+    ///
+    /// Each read clones the data, so keep your values cheap to clone.
+    /// If you want to store a lot of data you should wrap it in `Arc<Mutex<…>>` so it is cheap to clone.
     ///
     /// This will be saved between different program runs if you use the `persistence` feature.
     ///

egui/src/style.rs

@@ -257,6 +257,7 @@ impl Visuals {
         self.widgets.active.text_color()
     }
 
+    /// Window background color.
     #[inline(always)]
     pub fn window_fill(&self) -> Color32 {
         self.widgets.noninteractive.bg_fill

egui/src/util/id_type_map.rs

@@ -294,7 +294,10 @@ use crate::Id;
 // TODO: make IdTypeMap generic over the key (`Id`), and make a library of IdTypeMap.
 /// Stores values identified by an [`Id`] AND a the [`std::any::TypeId`] of the value.
 ///
-/// so it maps `(Id, TypeId)` to any value you want.
+/// In other words, it maps `(Id, TypeId)` to any value you want.
+///
+/// Values are cloned when read, so keep them small and light.
+/// If you want to store something bigger, wrap them in `Arc<Mutex<…>>`.
 ///
 /// Values can either be "persisted" (serializable) or "temporary" (cleared when egui is shut down).
 ///
@@ -346,6 +349,8 @@ impl IdTypeMap {
     }
 
     /// Read a value without trying to deserialize a persisted value.
+    ///
+    /// The call clones the value (if found), so make sure it is cheap to clone!
     #[inline]
     pub fn get_temp<T: 'static + Clone>(&mut self, id: Id) -> Option<T> {
         let hash = hash(TypeId::of::<T>(), id);
@@ -356,6 +361,8 @@ impl IdTypeMap {
     }
 
     /// Read a value, optionally deserializing it if available.
+    ///
+    /// The call clones the value (if found), so make sure it is cheap to clone!
     #[inline]
     pub fn get_persisted<T: SerializableAny>(&mut self, id: Id) -> Option<T> {
         let hash = hash(TypeId::of::<T>(), id);

egui/src/widgets/color_picker.rs

@@ -337,19 +337,19 @@ pub fn color_picker_color32(ui: &mut Ui, srgba: &mut Color32, alpha: Alpha) -> b
 }
 
 pub fn color_edit_button_hsva(ui: &mut Ui, hsva: &mut Hsva, alpha: Alpha) -> Response {
-    let pupup_id = ui.auto_id_with("popup");
+    let popup_id = ui.auto_id_with("popup");
-    let open = ui.memory().is_popup_open(pupup_id);
+    let open = ui.memory().is_popup_open(popup_id);
     let mut button_response = color_button(ui, (*hsva).into(), open);
     if ui.style().explanation_tooltips {
         button_response = button_response.on_hover_text("Click to edit color");
     }
 
     if button_response.clicked() {
-        ui.memory().toggle_popup(pupup_id);
+        ui.memory().toggle_popup(popup_id);
     }
     // TODO: make it easier to show a temporary popup that closes when you click outside it
-    if ui.memory().is_popup_open(pupup_id) {
+    if ui.memory().is_popup_open(popup_id) {
-        let area_response = Area::new(pupup_id)
+        let area_response = Area::new(popup_id)
             .order(Order::Foreground)
             .default_pos(button_response.rect.max)
             .show(ui.ctx(), |ui| {

emath/src/lib.rs

@@ -8,6 +8,12 @@
 //! * X+ is right and Y+ is down.
 //! * (0,0) is left top.
 //! * Dimension order is always `x y`
+//!
+//! ## Integrating with other math libraries.
+//! `emath` does not strive to become a general purpose or all-powerful math library.
+//!
+//! For that, use something else ([`glam`](https://docs.rs/glam), [`nalgebra`](https://docs.rs/nalgebra), …)
+//! and enable the `mint` feature flag in `emath` to enable implicit conversion to/from `emath`.
 
 // Forbid warnings in release builds:
 #![cfg_attr(not(debug_assertions), deny(warnings))]

emath/src/pos2.rs

@@ -13,12 +13,14 @@ use crate::*;
 #[cfg_attr(feature = "serde", derive(serde::Deserialize, serde::Serialize))]
 #[cfg_attr(feature = "bytemuck", derive(bytemuck::Pod, bytemuck::Zeroable))]
 pub struct Pos2 {
+    /// How far to the right.
     pub x: f32,
+    /// How far down.
     pub y: f32,
     // implicit w = 1
 }
 
-/// `pos2(x,y) == Pos2::new(x, y)`
+/// `pos2(x, y) == Pos2::new(x, y)`
 #[inline(always)]
 pub const fn pos2(x: f32, y: f32) -> Pos2 {
     Pos2 { x, y }
@@ -91,6 +93,7 @@ impl From<&Pos2> for (f32, f32) {
 
 #[cfg(feature = "mint")]
 impl From<mint::Point2<f32>> for Pos2 {
+    #[inline(always)]
     fn from(v: mint::Point2<f32>) -> Self {
         Self::new(v.x, v.y)
     }
@@ -98,6 +101,7 @@ impl From<mint::Point2<f32>> for Pos2 {
 
 #[cfg(feature = "mint")]
 impl From<Pos2> for mint::Point2<f32> {
+    #[inline(always)]
     fn from(v: Pos2) -> Self {
         Self { x: v.x, y: v.y }
     }

emath/src/vec2.rs

@@ -11,11 +11,13 @@ use std::ops::{Add, AddAssign, Div, Mul, MulAssign, Neg, Sub, SubAssign};
 #[cfg_attr(feature = "serde", derive(serde::Deserialize, serde::Serialize))]
 #[cfg_attr(feature = "bytemuck", derive(bytemuck::Pod, bytemuck::Zeroable))]
 pub struct Vec2 {
+    /// Rightwards. Width.
     pub x: f32,
+    /// Downwards. Height.
     pub y: f32,
 }
 
-/// `vec2(x,y) == Vec2::new(x, y)`
+/// `vec2(x, y) == Vec2::new(x, y)`
 #[inline(always)]
 pub const fn vec2(x: f32, y: f32) -> Vec2 {
     Vec2 { x, y }
@@ -88,6 +90,7 @@ impl From<&Vec2> for (f32, f32) {
 
 #[cfg(feature = "mint")]
 impl From<mint::Vector2<f32>> for Vec2 {
+    #[inline]
     fn from(v: mint::Vector2<f32>) -> Self {
         Self::new(v.x, v.y)
     }
@@ -95,6 +98,7 @@ impl From<mint::Vector2<f32>> for Vec2 {
 
 #[cfg(feature = "mint")]
 impl From<Vec2> for mint::Vector2<f32> {
+    #[inline]
     fn from(v: Vec2) -> Self {
         Self { x: v.x, y: v.y }
     }

epaint/src/text/fonts.rs

@@ -243,7 +243,7 @@ pub struct Fonts {
 
 impl Fonts {
     /// Create a new [`Fonts`] for text layout.
-    /// This call is expensive, so only create on [`Fonts`] and then reuse it.
+    /// This call is expensive, so only create one [`Fonts`] and then reuse it.
     pub fn new(pixels_per_point: f32, definitions: FontDefinitions) -> Self {
         assert!(
             0.0 < pixels_per_point && pixels_per_point < 100.0,

sh/check.sh

@@ -17,7 +17,7 @@ cargo fmt --all -- --check
 
 cargo doc -p emath -p epaint -p egui -p eframe -p epi -p egui_web -p egui-winit -p egui_glium -p egui_glow --lib --no-deps --all-features
 cargo doc -p egui_web --target wasm32-unknown-unknown --lib --no-deps --all-features
-cargo doc --document-private-items --no-deps --all-features --  -D warnings
+cargo doc --document-private-items --no-deps --all-features
 
 (cd emath && cargo check --no-default-features)
 (cd epaint && cargo check --no-default-features --features "single_threaded")