Add doc comments

crates/viewer/re_ui/src/help.rs

@@ -2,26 +2,30 @@ use crate::icon_text::{IconText, IconTextItem};
 use crate::{design_tokens, icons, ColorToken, DesignTokens, Scale, UiExt};
 use egui::{OpenUrl, RichText, Sense, TextBuffer, Ui, UiBuilder};
 
+/// A help popup where you can show markdown text and controls as a table.
 #[derive(Debug, Clone)]
 pub struct Help<'a> {
     title: String,
     docs_link: Option<String>,
     sections: Vec<HelpSection<'a>>,
 }
 
+/// A single section, seperated by a [`egui::Separator`].
 #[derive(Debug, Clone)]
 enum HelpSection<'a> {
     Markdown(String),
     Controls(Vec<ControlRow<'a>>),
 }
 
+/// A single row in the controls table.
 #[derive(Debug, Clone)]
 pub struct ControlRow<'a> {
     text: String,
     items: IconText<'a>,
 }
 
 impl<'a> ControlRow<'a> {
+    /// Create a new control row.
     #[allow(clippy::needless_pass_by_value)]
     pub fn new(text: impl ToString, items: IconText<'a>) -> Self {
         Self {
@@ -32,6 +36,7 @@ impl<'a> ControlRow<'a> {
 }
 
 impl<'a> Help<'a> {
+    /// Create a new help popup.
     #[allow(clippy::needless_pass_by_value)]
     pub fn new(title: impl ToString) -> Self {
         Self {
@@ -41,13 +46,15 @@ impl<'a> Help<'a> {
         }
     }
 
+    /// Add a docs link, to be shown in the top right corner.
     #[allow(clippy::needless_pass_by_value)]
     #[inline]
     pub fn docs_link(mut self, docs_link: impl ToString) -> Self {
         self.docs_link = Some(docs_link.to_string());
         self
     }
 
+    /// Add a markdown section.
     #[allow(clippy::needless_pass_by_value)]
     #[inline]
     pub fn markdown(mut self, markdown: impl ToString) -> Self {
@@ -56,12 +63,14 @@ impl<'a> Help<'a> {
         self
     }
 
+    /// Add a controls section.
     #[inline]
     pub fn controls(mut self, controls: Vec<ControlRow<'a>>) -> Self {
         self.sections.push(HelpSection::Controls(controls));
         self
     }
 
+    /// Add a single control row to the last controls section.
     #[allow(clippy::needless_pass_by_value)]
     #[inline]
     pub fn control(mut self, label: impl ToString, items: IconText<'a>) -> Self {
@@ -74,6 +83,7 @@ impl<'a> Help<'a> {
         self
     }
 
+    /// Create a new empty control section.
     #[inline]
     pub fn control_separator(mut self) -> Self {
         self.sections.push(HelpSection::Controls(vec![]));
@@ -92,6 +102,7 @@ impl<'a> Help<'a> {
         });
     }
 
+    /// Show the help popup. Usually you want to show this in [`egui::Response::on_hover_ui`].
     pub fn ui(&self, ui: &mut Ui) {
         egui::Sides::new().show(
             ui,
@@ -134,11 +145,10 @@ impl<'a> Help<'a> {
                 }
                 HelpSection::Controls(controls) => {
                     for row in controls {
-                        egui::Sides::new().show(
+                        egui::Sides::new().spacing(8.0).show(
                             ui,
                             |ui| {
                                 ui.strong(RichText::new(&row.text).size(11.0));
-                                ui.add_space(8.0);
                             },
                             |ui| {
                                 ui.set_height(DesignTokens::small_icon_size().y);

crates/viewer/re_ui/src/icon_text.rs

@@ -18,22 +18,28 @@ impl<'a> IconTextItem<'a> {
     }
 }
 
+/// Helper to show text with icons in a row.
+/// Usually created via the [`crate::icon_text!`] macro.
 #[derive(Default, Debug, Clone)]
 pub struct IconText<'a>(pub Vec<IconTextItem<'a>>);
 
 impl<'a> IconText<'a> {
+    /// Create a new, empty `IconText`.
     pub fn new() -> Self {
         Self(Vec::new())
     }
 
+    /// Add an icon to the row.
     pub fn icon(&mut self, icon: Icon) {
         self.0.push(IconTextItem::Icon(icon));
     }
 
+    /// Add text to the row.
     pub fn text(&mut self, text: impl Into<Cow<'a, str>>) {
         self.0.push(IconTextItem::Text(text.into()));
     }
 
+    /// Add an item to the row.
     pub fn add(&mut self, item: impl Into<IconTextItem<'a>>) {
         self.0.push(item.into());
     }
@@ -57,6 +63,7 @@ impl<'a> From<String> for IconTextItem<'a> {
     }
 }
 
+/// Create an [`IconText`] with the given items.
 #[macro_export]
 macro_rules! icon_text {
     ($($item:expr),* $(,)?) => {{
@@ -66,6 +73,8 @@ macro_rules! icon_text {
     }};
 }
 
+/// Helper to add [`egui::Modifiers`] as text with icons.
+/// Will automatically show Cmd/Ctrl based on the OS.
 pub struct ModifiersText<'a>(pub Modifiers, pub &'a egui::Context);
 
 impl<'a> From<ModifiersText<'a>> for IconTextItem<'static> {
@@ -88,6 +97,7 @@ impl<'a> From<ModifiersText<'a>> for IconTextItem<'static> {
     }
 }
 
+/// Helper to show mouse buttons as text/icons.
 pub struct MouseButtonText(pub egui::PointerButton);
 
 impl From<MouseButtonText> for IconTextItem<'static> {