From 2e819a11f2bbe86a9b32a8c0c3b2c17df494d9b9 Mon Sep 17 00:00:00 2001
From: user202729 <25191436+user202729@users.noreply.github.com>
Date: Wed, 17 Dec 2025 22:53:01 +0800
Subject: [PATCH] Some documentation improvements (#4631)

---
 doc/api.md           | 2 --
 include/fmt/base.h   | 6 +++++-
 include/fmt/format.h | 8 ++++++++
 3 files changed, 13 insertions(+), 3 deletions(-)

diff --git a/doc/api.md b/doc/api.md
index 53d8f710..57cdf82a 100644
--- a/doc/api.md
+++ b/doc/api.md
@@ -321,8 +321,6 @@ parameterized version.
 
 ::: arg(const Char*, const T&)
 
-Named arguments are not supported in compile-time checks at the moment.
-
 ### Compatibility
 
 ::: basic_string_view
diff --git a/include/fmt/base.h b/include/fmt/base.h
index 23c76dac..3bd16fcf 100644
--- a/include/fmt/base.h
+++ b/include/fmt/base.h
@@ -2310,7 +2310,7 @@ template <typename Context> class value {
   template <typename T, FMT_ENABLE_IF(!has_formatter<T, char_type>())>
   FMT_CONSTEXPR value(const T&, custom_tag) {
     // Cannot format an argument; to make type T formattable provide a
-    // formatter<T> specialization: https://fmt.dev/latest/api.html#udt.
+    // formatter<T> specialization: https://fmt.dev/latest/api#udt.
     type_is_unformattable_for<T, char_type> _;
   }
 
@@ -2847,6 +2847,10 @@ using vargs =
  * **Example**:
  *
  *     fmt::print("The answer is {answer}.", fmt::arg("answer", 42));
+ *
+ * Named arguments passed with `fmt::arg` are not supported
+ * in compile-time checks, but `"answer"_a=42` are compile-time checked in
+ * sufficiently new compilers. See `operator""_a()`.
  */
 template <typename Char, typename T>
 inline auto arg(const Char* name, const T& arg) -> detail::named_arg<Char, T> {
diff --git a/include/fmt/format.h b/include/fmt/format.h
index 5f3324fd..7c486691 100644
--- a/include/fmt/format.h
+++ b/include/fmt/format.h
@@ -4147,6 +4147,14 @@ template <typename T, typename Char = char> struct nested_formatter {
 
 inline namespace literals {
 #if FMT_USE_NONTYPE_TEMPLATE_ARGS
+/**
+ * User-defined literal equivalent of `fmt::arg`, but with compile-time checks.
+ *
+ * **Example**:
+ *
+ *     using namespace fmt::literals;
+ *     fmt::print("The answer is {answer}.", "answer"_a=42);
+ */
 template <detail::fixed_string S> constexpr auto operator""_a() {
   using char_t = remove_cvref_t<decltype(*S.data)>;
   return detail::udl_arg<char_t, sizeof(S.data) / sizeof(char_t), S>();