diff --git a/crates/egui/src/ui.rs b/crates/egui/src/ui.rs
index 7a4b1b21..a73e4e91 100644
--- a/crates/egui/src/ui.rs
+++ b/crates/egui/src/ui.rs
@@ -1748,6 +1748,7 @@ impl Ui {
         })
     }
 
+    /// Set z-index and layer id at the same time
     pub fn with_layer<R>(
         &mut self,
         layer: ZLayer,
@@ -1759,6 +1760,10 @@ impl Ui {
         })
     }
 
+    /// Set z-index for all shapes drawn on the current layer
+    ///
+    /// Note that this z-index is for this layer only. The draw order of area
+    /// layers takes precedence over this z-index.
     pub fn with_z<R>(
         &mut self,
         z: layers::ZOrder,