Migrate docs

include/fmt/os.h

@@ -79,46 +79,33 @@ FMT_BEGIN_NAMESPACE
 FMT_BEGIN_EXPORT
 
 /**
-  \rst
-  A reference to a null-terminated string. It can be constructed from a C
-  string or ``std::string``.
-
-  You can use one of the following type aliases for common character types:
-
-  +---------------+-----------------------------+
-  | Type          | Definition                  |
-  +===============+=============================+
-  | cstring_view  | basic_cstring_view<char>    |
-  +---------------+-----------------------------+
-  | wcstring_view | basic_cstring_view<wchar_t> |
-  +---------------+-----------------------------+
-
-  This class is most useful as a parameter type to allow passing
-  different types of strings to a function, for example::
-
-    template <typename... Args>
-    std::string format(cstring_view format_str, const Args & ... args);
-
-    format("{}", 42);
-    format(std::string("{}"), 42);
-  \endrst
+ * A reference to a null-terminated string. It can be constructed from a C
+ * string or `std::string`.
+ *
+ * You can use one of the following type aliases for common character types:
+ *
+ * +---------------+-----------------------------+
+ * | Type          | Definition                  |
+ * +===============+=============================+
+ * | cstring_view  | basic_cstring_view<char>    |
+ * +---------------+-----------------------------+
+ * | wcstring_view | basic_cstring_view<wchar_t> |
+ * +---------------+-----------------------------+
+ *
+ * This class is most useful as a parameter type for functions that wrap C APIs.
  */
 template <typename Char> class basic_cstring_view {
  private:
   const Char* data_;
 
  public:
-  /** Constructs a string reference object from a C string. */
+  /// Constructs a string reference object from a C string.
   basic_cstring_view(const Char* s) : data_(s) {}
 
-  /**
-    \rst
-    Constructs a string reference from an ``std::string`` object.
-    \endrst
-   */
+  /// Constructs a string reference from an `std::string` object.
   basic_cstring_view(const std::basic_string<Char>& s) : data_(s.c_str()) {}
 
-  /** Returns the pointer to a C string. */
+  /// Returns the pointer to a C string.
   auto c_str() const -> const Char* { return data_; }
 };
 
@@ -137,33 +124,30 @@ FMT_API std::system_error vwindows_error(int error_code, string_view format_str,
                                          format_args args);
 
 /**
- \rst
- Constructs a :class:`std::system_error` object with the description
- of the form
-
- .. parsed-literal::
-   *<message>*: *<system-message>*
-
- where *<message>* is the formatted message and *<system-message>* is the
- system message corresponding to the error code.
- `error_code` is a Windows error code as given by ``GetLastError``.
- If `error_code` is not a valid error code such as -1, the system message
- will look like "error -1".
-
- **Example**:
-
-   // This throws a system_error with the description
-   //   cannot open file 'madeup': The system cannot find the file specified.
-   // or similar (system message may vary).
-   const char *filename = "madeup";
-   LPOFSTRUCT of = LPOFSTRUCT();
-   HFILE file = OpenFile(filename, &of, OF_READ);
-   if (file == HFILE_ERROR) {
-     throw fmt::windows_error(GetLastError(),
-                              "cannot open file '{}'", filename);
-   }
- \endrst
-*/
+ * Constructs a `std::system_error` object with the description of the form
+ *
+ *     <message>: <system-message>
+ *
+ * where `<message>` is the formatted message and `<system-message>` is the
+ * system message corresponding to the error code.
+ * `error_code` is a Windows error code as given by `GetLastError`.
+ * If `error_code` is not a valid error code such as -1, the system message
+ * will look like "error -1".
+ *
+ * **Example**:
+ *
+ *     // This throws a system_error with the description
+ *     //   cannot open file 'madeup': The system cannot find the file
+ * specified.
+ *     // or similar (system message may vary).
+ *     const char *filename = "madeup";
+ *     LPOFSTRUCT of = LPOFSTRUCT();
+ *     HFILE file = OpenFile(filename, &of, OF_READ);
+ *     if (file == HFILE_ERROR) {
+ *       throw fmt::windows_error(GetLastError(),
+ *                                "cannot open file '{}'", filename);
+ *     }
+ */
 template <typename... Args>
 std::system_error windows_error(int error_code, string_view message,
                                 const Args&... args) {
@@ -401,9 +385,7 @@ class file_buffer final : public buffer<char> {
 
 }  // namespace detail
 
-// Added {} below to work around default constructor error known to
-// occur in Xcode versions 7.2.1 and 8.2.1.
-constexpr detail::buffer_size buffer_size{};
+constexpr auto buffer_size = detail::buffer_size();
 
 /// A fast output stream for writing from a single thread. Writing from
 /// multiple threads without external synchronization may result in a data race.
@@ -435,19 +417,17 @@ class FMT_API ostream {
 };
 
 /**
-  \rst
-  Opens a file for writing. Supported parameters passed in `params`:
-
-  * ``<integer>``: Flags passed to `open
-    <https://pubs.opengroup.org/onlinepubs/007904875/functions/open.html>`_
-    (``file::WRONLY | file::CREATE | file::TRUNC`` by default)
-  * ``buffer_size=<integer>``: Output buffer size
-
-  **Example**:
-
-    auto out = fmt::output_file("guide.txt");
-    out.print("Don't {}", "Panic");
-  \endrst
+ * Opens a file for writing. Supported parameters passed in `params`:
+ *
+ * - `<integer>`: Flags passed to [open](
+ *   https://pubs.opengroup.org/onlinepubs/007904875/functions/open.html)
+ *   (`file::WRONLY | file::CREATE | file::TRUNC` by default)
+ * - `buffer_size=<integer>`: Output buffer size
+ *
+ * **Example**:
+ *
+ *     auto out = fmt::output_file("guide.txt");
+ *     out.print("Don't {}", "Panic");
  */
 template <typename... T>
 inline auto output_file(cstring_view path, T... params) -> ostream {