Documentation improvements

doc/api.md

@@ -65,24 +65,9 @@ specified otherwise.
 
 ::: format_to_n(OutputIt, size_t, format_string<T...>, T&&...)
 
-::: formatted_size(format_string<T...>, T&&...)
-
 ::: format_to_n_result
 
-### Compile-Time Format String Checks
+::: formatted_size(format_string<T...>, T&&...)
-
-Compile-time format string checks are enabled by default on compilers
-that support C++20 `consteval`. On older compilers you can use the
-`FMT_STRING <legacy-checks>`{.interpreted-text role="ref"}: macro
-defined in `fmt/format.h` instead.
-
-Unused arguments are allowed as in Python's `str.format` and ordinary functions.
-
-::: basic_format_string
-
-::: format_string
-
-::: runtime(string_view)
 
 <a id="udt"></a>
 ### Formatting User-Defined Types
@@ -262,6 +247,20 @@ You can also write a formatter for a hierarchy of classes:
 Providing both a `formatter` specialization and a `format_as` overload
 is disallowed.
 
+### Compile-Time Format String Checks
+
+Compile-time format string checks are enabled by default on compilers
+that support C++20 `consteval`. On older compilers you can use the
+[FMT_STRING](legacy-checks>) macro defined in `fmt/format.h` instead.
+
+Unused arguments are allowed as in Python's `str.format` and ordinary functions.
+
+::: basic_format_string
+
+::: format_string
+
+::: runtime(string_view)
+
 ### Named Arguments
 
 ::: arg(const Char*, const T&)
@@ -271,23 +270,23 @@ Named arguments are not supported in compile-time checks at the moment.
 ### Argument Lists
 
 You can create your own formatting function with compile-time checks and
-small binary footprint, for example (<https://godbolt.org/z/vajfWEG4b>):
+small binary footprint, for example ([run](https://godbolt.org/z/b9Pbasvzc)):
 
 ```c++
 #include <fmt/base.h>
 
 void vlog(const char* file, int line,
-          fmt::string_view format, fmt::format_args args) {
+          fmt::string_view fmt, fmt::format_args args) {
-  fmt::print("{}: {}: {}", file, line, fmt::vformat(format, args));
+  fmt::print("{}: {}: {}", file, line, fmt::vformat(fmt, args));
 }
 
 template <typename... T>
 void log(const char* file, int line,
-         fmt::format_string<T...> format, T&&... args) {
+         fmt::format_string<T...> fmt, T&&... args) {
-  vlog(file, line, format, fmt::make_format_args(args...));
+  vlog(file, line, fmt, fmt::make_format_args(args...));
 }
 
-#define MY_LOG(format, ...) log(__FILE__, __LINE__, format, __VA_ARGS__)
+#define MY_LOG(fmt, ...) log(__FILE__, __LINE__, fmt, __VA_ARGS__)
 
 MY_LOG("invalid squishiness: {}", 42);
 ```
@@ -300,45 +299,21 @@ parameterized version.
 
 ::: basic_format_args
 
-:: {.doxygentypedef}
+::: format_args
-fmt::format_args
-::
 
-:: {.doxygenclass members=""}
+::: basic_format_arg
-fmt::basic_format_arg
-::
 
-:: {.doxygenclass members=""}
+::: basic_format_parse_context
-fmt::basic_format_parse_context
-::
 
-:: {.doxygenclass members=""}
+::: context
-fmt::context
-::
 
-:: {.doxygentypedef}
+::: format_context
-fmt::format_context
-::
-
-### Dynamic Argument Lists {#args-api}
-
-The header `fmt/args.h` provides `dynamic_format_arg_store`, a
-builder-like API that can be used to construct format argument lists
-dynamically.
-
-:: {.doxygenclass members=""}
-fmt::dynamic_format_arg_store
-::
 
 ### Compatibility
 
-:: {.doxygenclass members=""}
+::: basic_string_view
-fmt::basic_string_view
-::
 
-:: {.doxygentypedef}
+::: string_view
-fmt::string_view
-::
 
 ## Format API
 
@@ -350,12 +325,6 @@ formatting functions and locale support.
 
 ::: vformat(string_view, format_args)
 
-### Literal-Based API
-
-The following user-defined literals are defined in `fmt/format.h`.
-
-::: operator""_a()
-
 ### Utilities
 
 ::: ptr(T)
@@ -366,9 +335,7 @@ The following user-defined literals are defined in `fmt/format.h`.
 
 ::: group_digits(T)
 
-:: {.doxygenclass members=""}
+<!-- TODO ::: detail::buffer -->
-fmt::detail::buffer
-::
 
 ::: basic_memory_buffer
 
@@ -383,6 +350,12 @@ functions.
 
 ::: format_system_error
 
+### Literal-Based API
+
+The following user-defined literals are defined in `fmt/format.h`.
+
+::: operator""_a()
+
 ### Custom Allocators
 
 The {fmt} library supports custom dynamic memory allocators. A custom
@@ -439,7 +412,8 @@ parameter to avoid the expensive `<locale>` include.
 
 ::: formatted_size(const Locale&, format_string<T...>, T&&...)
 
-### Legacy Compile-Time Format String Checks {#legacy-checks}
+<a id="legacy-checks"></a>
+### Legacy Compile-Time Format String Checks
 
 `FMT_STRING` enables compile-time checks on older compilers. It requires
 C++14 or later and is a no-op in C++11.
@@ -452,7 +426,8 @@ To force the use of legacy compile-time checks, define the preprocessor
 variable `FMT_ENFORCE_COMPILE_STRING`. When set, functions accepting
 `FMT_STRING` will fail to compile with regular strings.
 
-## Range and Tuple Formatting {#ranges-api}
+<a id="ranges-api"></a>
+## Range and Tuple Formatting
 
 The library also supports convenient formatting of ranges and tuples:
 
@@ -475,7 +450,8 @@ separator:
 
 ::: join(It, Sentinel, string_view)
 
-## Date and Time Formatting {#chrono-api}
+<a id="chrono-api"></a>
+## Date and Time Formatting
 
 `fmt/chrono.h` provides formatters for
 
@@ -580,23 +556,15 @@ FMT_COMPILE
 
 ::: fg(detail::color_type)
 
-:: {.doxygenfunction}
+::: bg(detail::color_type)
-bg(detail::color_type)
-::
 
-:: {.doxygenfunction}
+::: styled(const T&, text_style)
-styled(const T& value, text_style ts)
-::
 
 ## System APIs {#os-api}
 
-:: {.doxygenclass members=""}
+::: ostream
-fmt::ostream
-::
 
-:: {.doxygenfunction}
+::: windows_error
-fmt::windows_error
-::
 
 ## `std::ostream` Support {#ostream-api}
 
@@ -621,13 +589,16 @@ you should provide a `formatter` specialization inherited from
     std::string s = fmt::format("The date is {}", date{2012, 12, 9});
     // s == "The date is 2012-12-9"
 
-:: {.doxygenfunction}
+::: streamed(const T&)
-streamed(const T &)
-::
 
-:: {.doxygenfunction}
+::: print(std::ostream&, format_string<T...>, T&&...)
-print(std::ostream &os, format_string\<T\...\> fmt, T&&\... args)
+
-::
+## Dynamic Argument Lists {#args-api}
+
+The header `fmt/args.h` provides `dynamic_format_arg_store`, a builder-like API
+that can be used to construct format argument lists dynamically.
+
+::: dynamic_format_arg_store
 
 ## `printf` Formatting {#printf-api}
 
@@ -638,17 +609,11 @@ with the POSIX extension for positional arguments. Unlike their standard
 counterparts, the `fmt` functions are type-safe and throw an exception
 if an argument type doesn\'t match its format specification.
 
-:: {.doxygenfunction}
+::: printf(string_view, const T&...)
-printf(string_view fmt, const T&\... args) -\> int
-::
 
-:: {.doxygenfunction}
+::: fprintf(std::FILE*, const S&, const T&...)
-fprintf(std::FILE \*f, const S &fmt, const T&\... args) -\> int
-::
 
-:: {.doxygenfunction}
+::: sprintf(const S&, const T&...)
-sprintf(const S&, const T&\...)
-::
 
 ## `wchar_t` Support {#xchar-api}
 

doc/fmt.css

@@ -1,3 +1,7 @@
+.md-grid {
+  max-width: 960px;
+}
+
 .docblock {
   border-left: .05rem solid var(--md-primary-fg-color);
 }

include/fmt/base.h

@@ -1817,8 +1817,8 @@ FMT_DEPRECATED FMT_CONSTEXPR auto visit_format_arg(
  * should only be used as a parameter type in type-erased functions such as
  * `vformat`:
  *
- *     void vlog(string_view format_str, format_args args);  // OK
+ *     void vlog(fmt::string_view fmt, fmt::format_args args);  // OK
- *     format_args args = make_format_args();  // Error: dangling reference
+ *     fmt::format_args args = fmt::make_format_args();  // Dangling reference
  */
 template <typename Context> class basic_format_args {
  public:
@@ -2029,7 +2029,7 @@ inline auto arg(const Char* name, const T& arg) -> detail::named_arg<Char, T> {
 }
 FMT_END_EXPORT
 
-/// An alias to `basic_format_args<format_context>`.
+/// An alias for `basic_format_args<format_context>`.
 // A separate type would result in shorter symbols but break ABI compatibility
 // between clang and gcc on ARM (#1919).
 FMT_EXPORT using format_args = basic_format_args<format_context>;
@@ -2994,7 +2994,7 @@ FMT_API void vprintln(FILE* f, string_view fmt, format_args args);
  *
  * **Example**:
  * 
- *     fmt::print("Elapsed time: {0:.2f} seconds", 1.23);
+ *     fmt::print("The answer is {}.", 42);
  */
 template <typename... T>
 FMT_INLINE void print(format_string<T...> fmt, T&&... args) {