From a59e178131461126ecd09888c56bce8d57f62e66 Mon Sep 17 00:00:00 2001
From: YgorSouza <43298013+YgorSouza@users.noreply.github.com>
Date: Thu, 26 Sep 2024 09:15:28 +0200
Subject: [PATCH] Document the fact that the hex_color macro is not const
 (#5169)

It cannot be made const with the current version of Rust, and that is
counterintuitive since it does compile-time checks, so we make that
clear in the documentation. It might be possible to make it const once
MSRV is bumped to 1.82.

* See <https://github.com/emilk/egui/issues/5160>
* [x] I have followed the instructions in the PR template
---
 crates/ecolor/src/hex_color_macro.rs   | 28 +++++++++++++++++++++++++-
 crates/ecolor/src/hex_color_runtime.rs |  4 ++--
 2 files changed, 29 insertions(+), 3 deletions(-)

diff --git a/crates/ecolor/src/hex_color_macro.rs b/crates/ecolor/src/hex_color_macro.rs
index a0a0729fdd1..fd1075dc639 100644
--- a/crates/ecolor/src/hex_color_macro.rs
+++ b/crates/ecolor/src/hex_color_macro.rs
@@ -1,15 +1,41 @@
-/// Construct a [`crate::Color32`] from a hex RGB or RGBA string.
+/// Construct a [`crate::Color32`] from a hex RGB or RGBA string literal.
 ///
 /// Requires the "color-hex" feature.
 ///
+/// The string is checked at compile time. If the format is invalid, compilation fails. The valid
+/// format is the one described in <https://drafts.csswg.org/css-color-4/#hex-color>. Only 6 (RGB) or 8 (RGBA)
+/// digits are supported, and the leading `#` character is optional.
+///
+/// Note that despite being checked at compile-time, this macro is not usable in `const` contexts
+/// because creating the [`crate::Color32`] instance requires floating-point arithmetic.
+///
 /// See also [`crate::Color32::from_hex`] and [`crate::Color32::to_hex`].
 ///
+/// # Examples
+///
 /// ```
 /// # use ecolor::{hex_color, Color32};
 /// assert_eq!(hex_color!("#202122"), Color32::from_hex("#202122").unwrap());
 /// assert_eq!(hex_color!("#202122"), Color32::from_rgb(0x20, 0x21, 0x22));
+/// assert_eq!(hex_color!("#202122"), hex_color!("202122"));
 /// assert_eq!(hex_color!("#abcdef12"), Color32::from_rgba_unmultiplied(0xab, 0xcd, 0xef, 0x12));
 /// ```
+///
+/// If the literal string has the wrong format, the code does not compile.
+///
+/// ```compile_fail
+/// let _ = ecolor::hex_color!("#abc");
+/// ```
+///
+/// ```compile_fail
+/// let _ = ecolor::hex_color!("#20212x");
+/// ```
+///
+/// The macro cannot be used in a `const` context.
+///
+/// ```compile_fail
+/// const COLOR: ecolor::Color32 = ecolor::hex_color!("#202122");
+/// ```
 #[macro_export]
 macro_rules! hex_color {
     ($s:literal) => {{
diff --git a/crates/ecolor/src/hex_color_runtime.rs b/crates/ecolor/src/hex_color_runtime.rs
index 3163fc5af7b..5b20258fa48 100644
--- a/crates/ecolor/src/hex_color_runtime.rs
+++ b/crates/ecolor/src/hex_color_runtime.rs
@@ -123,8 +123,8 @@ impl Color32 {
     /// Supports the 3, 4, 6, and 8-digit formats, according to the specification in
     /// <https://drafts.csswg.org/css-color-4/#hex-color>
     ///
-    /// To parse hex colors at compile-time (e.g. for use in `const` contexts)
-    /// use the macro [`crate::hex_color!`] instead.
+    /// To parse hex colors from string literals with compile-time checking, use the macro
+    /// [`crate::hex_color!`] instead.
     ///
     /// # Example
     /// ```rust