escape_string and format_options fixes

include/boost/mysql/character_set.hpp

@@ -55,7 +55,7 @@ struct character_set
      * \n
      * \par Function signature
      * The function signature should be:
-     * `std::size_t (*next_char)(boost::span<const unsigned char> r) noexcept`
+     * `std::size_t (*next_char)(boost::span<const unsigned char> r) noexcept`.
      */
     std::size_t (*next_char)(span<const unsigned char>) noexcept;
 };
@@ -76,7 +76,8 @@ constexpr character_set ascii_charset
 
 /**
  * \brief (EXPERIMENTAL) Settings required to format SQL queries client-side.
- * \see any_connection::format_opts
+ * \details
+ * The recommended way to obtain a value of this type is using \ref any_connection::format_opts.
  */
 struct format_options
 {

include/boost/mysql/escape_string.hpp

@@ -39,18 +39,11 @@ enum class quoting_context : char
 /**
  * \brief (EXPERIMENTAL) Escapes a string, making it safe for query composition.
  * \details
- * This is a low-level function, to be used by frameworks and other abstractions.
- * If you can, prefer higher-level functions like \ref format_sql.
- * \n
  * Given a string `input`, computes a string with special characters
  * escaped, and places it in `output`. This function is a low-level building
  * block for composing client-side queries with runtime string values without
  * incurring in SQL injection vulnerabilities.
- * \n
- * For instance, to compose a valid query from `SELECT * FROM employee WHERE company = '<runtime_value>'`,
- * where `runtime_value` is an untrusted runtime string, `runtime_value` should be escaped
- * using this function before concatenating strings. Otherwise, a malicious `runtime_value`
- * will be able to run arbitrary SQL statements in your server.
+ * If you can, prefer using higher-level functions like \ref format_sql.
  * \n
  * Escaping rules are different depending on the context a string is
  * being used in. `quot_ctx` identifies where the string will appear in