Improve docs

doc/api.md

@@ -273,7 +273,7 @@ You can create your own formatting function with compile-time checks and
 small binary footprint, for example ([run](https://godbolt.org/z/b9Pbasvzc)):
 
 ```c++
-#include <fmt/base.h>
+#include <fmt/format.h>
 
 void vlog(const char* file, int line,
           fmt::string_view fmt, fmt::format_args args) {
@@ -514,14 +514,14 @@ feature](https://en.cppreference.com/w/cpp/feature_test).
 
     #include <fmt/std.h>
 
-    std::variant<char, float> v0{'x'};
+    fmt::print("{}", std::variant<char, float>('x'));
-    // Prints "variant('x')"
+    // Output: variant('x')
-    fmt::print("{}", v0);
 
-    std::variant<std::monostate, char> v1;
+    fmt::print("{}", std::variant<std::monostate, char>());
-    // Prints "variant(monostate)"
+    // Output: variant(monostate)
 
-## Format String Compilation {#compile-api}
+<a id="compile-api"></a>
+## Format String Compilation
 
 `fmt/compile.h` provides format string compilation enabled via the
 `FMT_COMPILE` macro or the `_cf` user-defined literal. Format strings
@@ -615,26 +615,19 @@ if an argument type doesn\'t match its format specification.
 
 ::: sprintf(const S&, const T&...)
 
-## `wchar_t` Support {#xchar-api}
+<a id="xchar-api"></a>
+## Wide Strings
 
 The optional header `fmt/xchar.h` provides support for `wchar_t` and
 exotic character types.
 
-:: {.doxygenstruct}
+::: is_char
-fmt::is_char
-::
 
-:: {.doxygentypedef}
+::: wstring_view
-fmt::wstring_view
-::
 
-:: {.doxygentypedef}
+::: wformat_context
-fmt::wformat_context
-::
 
-:: {.doxygenfunction}
+::: to_wstring(const T&)
-fmt::to_wstring(const T &value)
-::
 
 ## Compatibility with C++20 `std::format`
 

include/fmt/format.h

@@ -813,25 +813,17 @@ FMT_BEGIN_EXPORT
 enum { inline_buffer_size = 500 };
 
 /**
-  \rst
+ * A dynamically growing memory buffer for trivially copyable/constructible
-  A dynamically growing memory buffer for trivially copyable/constructible types
+ * types with the first `SIZE` elements stored in the object itself. Most
-  with the first ``SIZE`` elements stored in the object itself.
+ * commonly used via the `memory_buffer` alias for `char`.
-
+ *
-  You can use the ``memory_buffer`` type alias for ``char`` instead.
+ * **Example**::
-
+ *
-  **Example**::
+ *     auto out = fmt::memory_buffer();
-
+ *     fmt::format_to(std::back_inserter(out), "The answer is {}.", 42);
-     auto out = fmt::memory_buffer();
+ *
-     fmt::format_to(std::back_inserter(out), "The answer is {}.", 42);
+ * This will append "The answer is 42." to `out`. The buffer content can be
-
+ * converted to `std::string` with `to_string(out)`.
-  This will append the following output to the ``out`` object:
-
-  .. code-block:: none
-
-     The answer is 42.
-
-  The output can be converted to an ``std::string`` with ``to_string(out)``.
-  \endrst
  */
 template <typename T, size_t SIZE = inline_buffer_size,
           typename Allocator = std::allocator<T>>
@@ -904,22 +896,14 @@ class basic_memory_buffer : public detail::buffer<T> {
   }
 
  public:
-  /**
+  /// Constructs a `basic_memory_buffer` object moving the content of the other
-    \rst
+  /// object to it.
-    Constructs a :class:`fmt::basic_memory_buffer` object moving the content
-    of the other object to it.
-    \endrst
-   */
   FMT_CONSTEXPR20 basic_memory_buffer(basic_memory_buffer&& other) noexcept
       : detail::buffer<T>(grow) {
     move(other);
   }
 
-  /**
+  /// Moves the content of the other `basic_memory_buffer` object to this one.
-    \rst
-    Moves the content of the other ``basic_memory_buffer`` object to this one.
-    \endrst
-   */
   auto operator=(basic_memory_buffer&& other) noexcept -> basic_memory_buffer& {
     FMT_ASSERT(this != &other, "");
     deallocate();
@@ -930,13 +914,11 @@ class basic_memory_buffer : public detail::buffer<T> {
   // Returns a copy of the allocator associated with this buffer.
   auto get_allocator() const -> Allocator { return alloc_; }
 
-  /**
+  /// Resizes the buffer to contain *count* elements. If T is a POD type new
-    Resizes the buffer to contain *count* elements. If T is a POD type new
+  /// elements may not be initialized.
-    elements may not be initialized.
-   */
   FMT_CONSTEXPR20 void resize(size_t count) { this->try_resize(count); }
 
-  /** Increases the buffer capacity to *new_capacity*. */
+  /// Increases the buffer capacity to *new_capacity*.
   void reserve(size_t new_capacity) { this->try_reserve(new_capacity); }
 
   using detail::buffer<T>::append;
@@ -965,7 +947,7 @@ FMT_BEGIN_EXPORT
 #  pragma clang diagnostic ignored "-Wweak-vtables"
 #endif
 
-/** An error reported from a formatting function. */
+/// An error reported from a formatting function.
 class FMT_SO_VISIBILITY("default") format_error : public std::runtime_error {
  public:
   using std::runtime_error::runtime_error;
@@ -1828,14 +1810,12 @@ inline auto find_escape(const char* begin, const char* end)
   }()
 
 /**
-  \rst
+ * Constructs a compile-time format string from a string literal *s*.
-  Constructs a compile-time format string from a string literal *s*.
+ *
-
+ * **Example**::
-  **Example**::
+ *
-
+ *     // A compile-time error because 'd' is an invalid specifier for strings.
-    // A compile-time error because 'd' is an invalid specifier for strings.
+ *     std::string s = fmt::format(FMT_STRING("{:d}"), "foo");
-    std::string s = fmt::format(FMT_STRING("{:d}"), "foo");
-  \endrst
  */
 #define FMT_STRING(s) FMT_STRING_IMPL(s, fmt::detail::compile_string, )
 
@@ -4028,13 +4008,11 @@ template <typename Char, size_t N>
 struct formatter<Char[N], Char> : formatter<basic_string_view<Char>, Char> {};
 
 /**
-  \rst
+ * Converts `p` to `const void*` for pointer formatting.
-  Converts ``p`` to ``const void*`` for pointer formatting.
+ *
-
+ * **Example**::
-  **Example**::
+ *
-
+ *     auto s = fmt::format("{}", fmt::ptr(p));
-    auto s = fmt::format("{}", fmt::ptr(p));
-  \endrst
  */
 template <typename T> auto ptr(T p) -> const void* {
   static_assert(std::is_pointer<T>::value, "");
@@ -4042,14 +4020,12 @@ template <typename T> auto ptr(T p) -> const void* {
 }
 
 /**
-  \rst
+ * Converts `e` to the underlying type.
-  Converts ``e`` to the underlying type.
+ *
-
+ * **Example**::
-  **Example**::
+ *
-
+ *     enum class color { red, green, blue };
-    enum class color { red, green, blue };
+ *     auto s = fmt::format("{}", fmt::underlying(color::red));
-    auto s = fmt::format("{}", fmt::underlying(color::red));
-  \endrst
  */
 template <typename Enum>
 constexpr auto underlying(Enum e) noexcept -> underlying_t<Enum> {
@@ -4199,15 +4175,11 @@ template <typename T, typename Char = char> struct nested_formatter {
 };
 
 /**
-  \rst
+ * Converts *value* to ``std::string`` using the default format for type *T*.
-  Converts *value* to ``std::string`` using the default format for type *T*.
+ *
-
+ * **Example**::
-  **Example**::
+ *
-
+ *     std::string answer = fmt::to_string(42);
-    #include <fmt/format.h>
-
-    std::string answer = fmt::to_string(42);
-  \endrst
  */
 template <typename T, FMT_ENABLE_IF(!std::is_integral<T>::value &&
                                     !detail::has_format_as<T>::value)>
@@ -4381,15 +4353,13 @@ constexpr auto operator""_a(const char* s, size_t) -> detail::udl_arg<char> {
 FMT_API auto vformat(string_view fmt, format_args args) -> std::string;
 
 /**
-  \rst
+ * Formats `args` according to specifications in `fmt` and returns the result
-  Formats ``args`` according to specifications in ``fmt`` and returns the result
+ * as a string.
-  as a string.
+ *
-
+ * **Example**::
-  **Example**::
+ *
-
+ *     #include <fmt/core.h>
-    #include <fmt/core.h>
+ *     std::string message = fmt::format("The answer is {}.", 42);
-    std::string message = fmt::format("The answer is {}.", 42);
-  \endrst
 */
 template <typename... T>
 FMT_NODISCARD FMT_INLINE auto format(format_string<T...> fmt, T&&... args)

support/mkdocstrings_handlers/cxx/__init__.py

@@ -52,7 +52,7 @@ def doxyxml2html(nodes: list[et.Element]):
       out += n.tail
   return out
 
-def get_template_params(node: et.Element) -> Optional[list[Definition]]:
+def convert_template_params(node: et.Element) -> Optional[list[Definition]]:
   templateparamlist = node.find('templateparamlist')
   if templateparamlist is None:
     return None
@@ -81,10 +81,20 @@ def convert_type(type: et.Element) -> str:
   result += type.tail.strip()
   return clean_type(result)
 
-def convert_param(param: et.Element) -> Definition:
+def convert_params(func: et.Element) -> Definition:
-  d = Definition(param.find('declname').text, 'param')
+  params = []
-  d.type = convert_type(param.find('type'))
+  for p in func.findall('param'):
-  return d
+    d = Definition(p.find('declname').text, 'param')
+    d.type = convert_type(p.find('type'))
+    params.append(d)
+  return params
+
+def convert_return_type(d: Definition, node: et.Element) -> None:
+  d.trailing_return_type = None
+  if d.type == 'auto' or d.type == 'constexpr auto':
+    parts = node.find('argsstring').text.split(' -> ')
+    if len(parts) > 1:
+      d.trailing_return_type = clean_type(parts[1])
 
 def render_decl(d: Definition) -> None:
   text = '<pre><code class="language-cpp">'
@@ -105,7 +115,7 @@ def render_decl(d: Definition) -> None:
     text += '(' + escape_html(params) + ')'
     if d.trailing_return_type:
       text += '\n ' \
-        if len(d.name) + len(params) + len(d.trailing_return_type) > 74 else ''
+        if len(d.name) + len(params) + len(d.trailing_return_type) > 68 else ''
       text += ' -> ' + escape_html(d.trailing_return_type)
   elif d.kind == 'typedef':
     text += ' = ' + escape_html(d.type)
@@ -182,20 +192,16 @@ class CxxHandler(BaseHandler):
       params = None
       kind = node.get('kind')
       if kind == 'function':
-        params = [convert_param(p) for p in node.findall('param')]
+        params = convert_params(node)
         node_param_str = ', '.join([p.type for p in params])
         if param_str and param_str != node_param_str:
           candidates.append(f'{name}({node_param_str})')
           continue
       d = Definition(name, kind)
       d.type = convert_type(node.find('type'))
-      d.template_params = get_template_params(node)
+      d.template_params = convert_template_params(node)
       d.params = params
-      d.trailing_return_type = None
+      convert_return_type(d, node)
-      if d.type == 'auto' or d.type == 'constexpr auto':
-        parts = node.find('argsstring').text.split(' -> ')
-        if len(parts) > 1:
-          d.trailing_return_type = clean_type(parts[1])
       d.desc = get_description(node)
       return d
     
@@ -207,16 +213,28 @@ class CxxHandler(BaseHandler):
       xml = et.parse(f)
       node = xml.find('compounddef')
       d = Definition(name, node.get('kind'))
-      d.template_params = get_template_params(node)
+      d.template_params = convert_template_params(node)
       d.desc = get_description(node)
       d.members = []
-      for m in node.findall('sectiondef[@kind="public-attrib"]/memberdef'):
+      for m in node.findall('sectiondef[@kind="public-attrib"]/memberdef') + \
+               node.findall('sectiondef[@kind="public-func"]/memberdef'):
         name = m.find('name').text
-        member = Definition(name if name else '', m.get('kind'))
+        # Doxygen incorrectly classifies members of private unnamed unions as
+        # public members of the containing class.
+        if name.endswith('_'):
+          continue
+        desc = get_description(m)
+        if len(desc) == 0:
+          continue
+        kind = m.get('kind')
+        member = Definition(name if name else '', kind)
         type = m.find('type').text
         member.type = type if type else ''
+        if kind == 'function':
+          member.params = convert_params(m)
+          convert_return_type(member, m)
         member.template_params = None
-        member.desc = get_description(m)
+        member.desc = desc
         d.members.append(member)
       return d