Install dot, try linking from header to datatypes.md. (#761)

Install Doxygen as well.  Ask for python 3.10 (standard in Ubuntu 22.04).

.readthedocs.yaml

@@ -7,7 +7,10 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.12"
+    python: "3.10"
+  apt_packages:
+    - doxygen
+    - graphviz
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:

NEWS

@@ -5,6 +5,7 @@
  - Support `PQfsize()` and `PQfmod()`. (#727)
  - Implement conversion from `string_view` to string. (#728)
  - Rename `splitconfig` to `splitconfig.py`. (#763)
+ - Document need for conversions more clearly, link to docs. (#757)
 7.8.1
  - Regenerate build files. Should fix ARM Mac build. (#715)
  - Reinstate `<ciso646>` that MSVC can't live with or without. (#713)

include/pqxx/field.hxx

@@ -103,6 +103,17 @@ public:
 
   /**
    * @name Content access
+   *
+   * You can read a field as any C++ type for which a conversion from
+   * PostgreSQL's text format is defined.  See @ref datatypes for how this
+   * works.  This mechanism is _weakly typed:_ the conversions do not care
+   * what SQL type a field had in the database, only that its actual contents
+   * convert to the target type without problems.  So for instance, you can
+   * read a `text` field as an `int`, so long as the string in the field spells
+   * out a valid `int` number.
+   *
+   * Many built-in types come with conversions predefined.  To find out how to
+   * add your own, see @ref datatypes.
    */
   //@{
   /// Read as `string_view`, or an empty one if null.

include/pqxx/result.hxx

@@ -291,6 +291,9 @@ public:
    *
    * @throws pqxx::usage_error if `func`'s number of parameters does not match
    * the number of columns in this result.
+   *
+   * The parameter types must have conversions from PostgreSQL's string format
+   * defined; see @ref datatypes.
    */
   template<typename CALLABLE> inline void for_each(CALLABLE &&func) const;
 

include/pqxx/row.hxx

@@ -181,6 +181,9 @@ public:
 
   /// Extract entire row's values into a tuple.
   /** Converts to the types of the tuple's respective fields.
+   *
+   * The types in the tuple must have conversions from PostgreSQL's text format
+   * defined; see @ref datatypes.
    *
    * @throw usage_error If the number of columns in the `row` does not match
    * the number of fields in `t`.
@@ -193,6 +196,9 @@ public:
 
   /// Extract entire row's values into a tuple.
   /** Converts to the types of the tuple's respective fields.
+   *
+   * The types must have conversions from PostgreSQL's text format defined;
+   * see @ref datatypes.
    *
    * @throw usage_error If the number of columns in the `row` does not match
    * the number of fields in `t`.

include/pqxx/transaction_base.hxx

@@ -465,6 +465,11 @@ public:
    * specify.  Unlike with the "exec" functions, processing can start before
    * all the data from the server is in.
    *
+   * The column types must all be types that have conversions from PostgreSQL's
+   * text format defined.  Many built-in types such as `int` or `std::string`
+   * have pre-defined conversions; if you want to define your own conversions
+   * for additional types, see @ref datatypes.
+   *
    * As a special case, tuple may contain `std::string_view` fields, but the
    * strings to which they point will only remain valid until you extract the
    * next row.  After that, the memory holding the string may be overwritten or
@@ -533,6 +538,10 @@ public:
    * the iteration is ongoing.  If `func` throws an exception, or the iteration
    * fails in some way, the only way out is to destroy the transaction and the
    * connection.
+   *
+   * Each of the parameter types must have a conversion from PostgreSQL's text
+   * format defined.  To define conversions for additional types, see
+   * @ref datatypes.
    */
   template<typename CALLABLE>
   auto for_stream(std::string_view query, CALLABLE &&func)