From b077cf910297884a4f1b431e8da99806ae925168 Mon Sep 17 00:00:00 2001
From: Emil Ernerfeldt <emil.ernerfeldt@gmail.com>
Date: Mon, 23 Mar 2026 15:50:57 +0100
Subject: [PATCH] Add some example docs to atoms (#7997)

---
 crates/egui/src/atomics/atom.rs  | 16 +++++++++++++++-
 crates/egui/src/atomics/atoms.rs | 19 +++++++++++++++++++
 2 files changed, 34 insertions(+), 1 deletion(-)

diff --git a/crates/egui/src/atomics/atom.rs b/crates/egui/src/atomics/atom.rs
index 4db7f12a9..6f289fcfb 100644
--- a/crates/egui/src/atomics/atom.rs
+++ b/crates/egui/src/atomics/atom.rs
@@ -4,7 +4,21 @@ use epaint::text::TextWrapMode;
 
 /// A low-level ui building block.
 ///
-/// Implements [`From`] for [`String`], [`str`], [`crate::Image`] and much more for convenience.
+/// This can be a piece of text, an image, or even a custom widget.
+/// It can be decorated with various layout hints, such as `grow`, `shrink`, `align`, and more.
+///
+/// `Atom` implements [`From`] for [`String`], [`str`], [`crate::Image`] and much more for convenience.
+///
+/// Many widgets take an `impl` [`crate::IntoAtoms`] parameter,
+/// which allows you to easily create atoms from tuples of text, images, and other atoms:
+/// ```
+/// # use egui::{Vec2, AtomExt, AtomKind, Atom, Image, Id};
+/// # egui::__run_test_ui(|ui| {
+/// let image = egui::include_image!("../../../eframe/data/icon.png");
+/// ui.button((image, "Click me!"));
+/// # });
+/// ```
+///
 /// You can directly call the `atom_*` methods on anything that implements `Into<Atom>`.
 /// ```
 /// # use egui::{Image, emath::Vec2};
diff --git a/crates/egui/src/atomics/atoms.rs b/crates/egui/src/atomics/atoms.rs
index 5051a7676..761db8eb6 100644
--- a/crates/egui/src/atomics/atoms.rs
+++ b/crates/egui/src/atomics/atoms.rs
@@ -8,6 +8,15 @@ use std::ops::{Deref, DerefMut};
 pub(crate) const ATOMS_SMALL_VEC_SIZE: usize = 2;
 
 /// A list of [`Atom`]s.
+///
+/// Many widgets take an `impl` [`IntoAtoms`] parameter,
+/// which allows you to easily create atoms from tuples of text, images, and other atoms:
+/// ```
+/// # use egui::{AtomExt, AtomKind, Atom, Image, Id, Vec2};
+/// # egui::__run_test_ui(|ui| {
+/// let image = egui::include_image!("../../../eframe/data/icon.png");
+/// ui.button((image, "Click me!"));
+/// # });
 #[derive(Clone, Debug, Default)]
 pub struct Atoms<'a>(SmallVec<[Atom<'a>; ATOMS_SMALL_VEC_SIZE]>);
 
@@ -192,6 +201,16 @@ where
 }
 
 /// Trait for turning a tuple of [`Atom`]s into [`Atoms`].
+///
+/// Many widgets take an `impl` [`IntoAtoms`] parameter,
+/// which allows you to easily create atoms from tuples of text, images, and other atoms:
+/// ```
+/// # use egui::{AtomExt, AtomKind, Atom, Image, Id, Vec2};
+/// # egui::__run_test_ui(|ui| {
+/// let image = egui::include_image!("../../../eframe/data/icon.png");
+/// ui.button((image, "Click me!"));
+/// # });
+/// ```
 pub trait IntoAtoms<'a> {
     fn collect(self, atoms: &mut Atoms<'a>);