Update documentation

Doxyfile

@@ -157,7 +157,7 @@ STRIP_FROM_PATH        =
 # specify the list of include paths that are normally passed to the compiler
 # using the -I flag.
 
-STRIP_FROM_INC_PATH    =
+STRIP_FROM_INC_PATH    = include
 
 # If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter (but
 # less readable) file names. This can be useful is your file systems doesn't
@@ -777,7 +777,7 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = include docs/howto.md README.md
+INPUT                  = include docs/howto.md README.md examples
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -856,7 +856,7 @@ EXCLUDE_SYMBOLS        =
 # that contain example code fragments that are included (see the \include
 # command).
 
-EXAMPLE_PATH           =
+EXAMPLE_PATH           = examples
 
 # If the value of the EXAMPLE_PATH tag contains directories, you can use the
 # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and

customdoxygen.css

@@ -1,7 +1,6 @@
 /* The standard CSS for doxygen 1.8.4 */
 
 body, table, div, p, dl {
-	// font: 400 14px/22px Roboto,sans-serif;
 	font: 13px "Lucida Grande", "Lucida Sans Unicode", Helvetica, Arial, Verdana, sans-serif;
 }
 
@@ -13,7 +12,6 @@ h1.groupheader {
 }
 
 .title {
-	//font: 400 14px/28px Roboto,sans-serif;
 	font-family: "Lucida Grande", "Lucida Sans Unicode", Helvetica, Arial, Verdana, sans-serif;
 	font-size: 24px;
 	font-weight: normal;
@@ -168,12 +166,10 @@ a.elRef {
 }
 
 a.code, a.code:visited {
-	//color: #4665A2;
 	color: rgb(51, 102, 204);
 }
 
 a.codeRef, a.codeRef:visited {
-	//color: #4665A2;
 	color: rgb(51, 102, 204);
 }
 
@@ -184,46 +180,33 @@ dl.el {
 }
 
 pre.fragment {
-        //border: 1px solid #C4CFE5;
 	border: solid 1px rgb(221, 221, 221);
 	border-radius: 3px;
-        //background-color: #FBFCFD;
 	background-color: rgb(248, 248, 248);
-        //padding: 4px 6px;
 	padding: 6px 10px;
-        //margin: 4px 8px 4px 2px;
 	margin: 15px 0px;
         overflow: auto;
         word-wrap: break-word;
         font-size:  9pt;
         line-height: 125%;
-        //font-family: monospace, fixed;
-	font-family: Consolas, "Liberation Mono", Courier, monospace;
+	font-family: "Courier New", Courier, Consolas, "Liberation Mono", monospace;
         font-size: 105%;
 }
 
 div.fragment {
-	//padding: 0px;
-     //padding: 4px 6px;
-     //margin: 0px;
-	//background-color: #FBFCFD;
-	//border: 1px solid #C4CFE5;
-
 	padding: 6px 10px;
 	margin: 15px 0px 15px 30px;
 	border: solid 1px rgb(221, 221, 221);
 	border-radius: 3px;
 	width: fit-content;
-
 	background-color: rgb(248, 248, 248);
 }
 
 div.line {
-	//font-family: monospace, fixed;
-	font-family: Consolas, "Liberation Mono", Courier, monospace;
-        font-size: 13px;
+	font-family: Courier, "Courier New", Consolas, "Liberation Mono", monospace;
+        font-size: 100%;
 	min-height: 13px;
-	line-height: 1.0;
+	line-height: 1.3;
 	text-wrap: unrestricted;
 	white-space: -moz-pre-wrap; /* Moz */
 	white-space: -pre-wrap;     /* Opera 4-6 */
@@ -371,31 +354,37 @@ img.footer {
 /* @group Code Colorization */
 
 span.keyword {
-	color: #008000
+	color: #10006b;
+	font-weight: bold;
 }
 
 span.keywordtype {
-	color: #604020
+	color: #613700;
+	font-weight: bold;
 }
 
 span.keywordflow {
-	color: #e08000
+	color: #002f5a;
+	font-weight: bold;
 }
 
 span.comment {
-	color: #800000
+	color: #700067;
+	font-style: italic;
 }
 
 span.preprocessor {
-	color: #806020
+	color: #1d7a00;
 }
 
 span.stringliteral {
-	color: #002080
+	color: #6b6b6b;
+	font-style: italic;
 }
 
 span.charliteral {
-	color: #008080
+	color: #6b6b6b;
+	font-style: italic;
 }
 
 span.vhdldigit {
@@ -460,7 +449,6 @@ th.dirtab {
 hr {
 	height: 0px;
 	border: none;
-	//border-top: 1px solid #4A6AAA;
 	border-top: 1px solid #444;
 }
 
@@ -1077,13 +1065,15 @@ dl.section
 
 dl.note
 {
-        //margin-left:-7px;
-	   margin-left: 0px;
-	   padding: 6px 0px 3px 8px;
-        //padding-left: 8px;
-        border-left:  6px solid;
-        border-color: #D0C000;
-	   background-color: #fff799
+	margin-left: 0px;
+	padding: 6px 6px 6px 8px;
+	border-left: 6px solid;
+	border-bottom: 1px solid;
+	border-top: 1px solid;
+	border-right: 1px solid;
+	border-color: rgb(173, 165, 77);
+	background-color: rgb(255, 250, 182);
+	width: fit-content;
 }
 
 dl.warning, dl.attention

docs/howto.md

@@ -31,7 +31,7 @@ int main() {
     ozo::rows_of<std::int64_t, std::optional<std::string>> rows;
 
     // Connection info with host and port to coonect to
-    ozo::connection_info<> conn_info("host=... port=...");
+    auto conn_info = ozo::make_connection_info("host=... port=...");
 
     // For _SQL literal
     using namespace ozo::literals;
@@ -86,7 +86,7 @@ The first argument of the tuple can not be a _NULL_, so here we do not to bother
 There is no mistake to expect nullable type for non-nullable result, but the opposite leads to run-time error in case of _NULL_ value result from database.
 
 ```cpp
-ozo::connection_info<> conn_info("host=... port=...");
+auto conn_info = ozo::make_connection_info("host=... port=...");
 ```
 
 Now we need to create a connection information for database to connect to. This is our connection provider which can create a connection for us as it will be needed (see more information about connection provider and how to get connection).
@@ -100,7 +100,7 @@ Here our query for database. There is a text with `_SQL` literal and single para
 Here is `request()` asynchronous function call.
 
 ```cpp
-ozo::request(ozo::make_provider(io, conn_info), query, ozo::into(res),
+ozo::request(ozo::make_connector(io, conn_info), query, ozo::into(res),
         [&](ozo::error_code ec, auto conn) {
 //...
 });
@@ -112,7 +112,7 @@ ozo::request(ozo::make_provider(io, conn_info), query, ozo::into(res),
 
 `ozo::into(res)` - the output perameter. In this case out parameter is back inserter iterator to the result vector. Note, what the life time of the output parameter managed by the user. In this case it correctly placed on stack since its lifetime overlaps `io.run()` call. But in more sophisticated code with callbacks it needs to be stored e.g. in shared pointer or something like this. The query output parameter can be iterator on container with appropriated data items, or it can be `ozo::result` which provides access to raw binary data. The second variant is not recommended since user must implement binary protocol parsing by self, but if it needed it can be used.
 
-`[&](ozo::error_code ec, auto conn)` - completion token parameter, in this case is callback lambda. In other cases it can be [boost::asio::use_future](https://www.boost.org/doc/libs/1_67_0/doc/html/boost_asio/reference/use_future.html), [boost::asio::yield_context](https://www.boost.org/doc/libs/1_67_0/doc/html/boost_asio/reference/yield_context.html) or any other [boost::asio::async_result](https://www.boost.org/doc/libs/1_67_0/doc/html/boost_asio/reference/async_result.html) comatible [Completion Token](https://www.boost.org/doc/libs/1_67_0/doc/html/boost_asio/reference/async_completion.html). The arguments of the call back are error code `ec` (which is namely `boost::system::error_code` for now) and the connection `conn` with which the query was made. Even if you got an error it is possible what there is an additional error context in the `conn`. Since there is no rooms to place context depended information about connection error into error code the context depended information provided via `error_message()` and `get_error_context()` functions. The first one returns error message from `libpq`, the second - additional context from `OZO`.
+`[&](ozo::error_code ec, auto conn)` - completion token parameter, in this case is callback lambda. In other cases it can be [boost::asio::use_future](https://www.boost.org/doc/libs/1_67_0/doc/html/boost_asio/reference/use_future.html), [boost::asio::yield_context](https://www.boost.org/doc/libs/1_67_0/doc/html/boost_asio/reference/yield_context.html) or any other [boost::asio::async_result](https://www.boost.org/doc/libs/1_67_0/doc/html/boost_asio/reference/async_result.html) compatible [Completion Token](https://www.boost.org/doc/libs/1_67_0/doc/html/boost_asio/reference/async_completion.html). The arguments of the call back are error code `ec` (which is namely `boost::system::error_code` for now) and the connection `conn` with which the query was made. Even if you got an error it is possible what there is an additional error context in the `conn`. Since there is no rooms to place context depended information about connection error into error code the context depended information provided via `error_message()` and `get_error_context()` functions. The first one returns error message from `libpq`, the second - additional context from `OZO`.
 
 `for(auto& row: res)` - so if there is no error we can handle result from the output container.
 
@@ -145,7 +145,7 @@ int main() {
 
     const auto query = "SELECT id, name FROM users_info WHERE amount>="_SQL + std::int64_t(25);
 
-    ozo::request(ozo::make_provider(io, conn_info), query, ozo::into(res),
+    ozo::request(ozo::make_connector(io, conn_info), query, ozo::into(res),
             [&](ozo::error_code ec, auto conn) {
     //...
     });

examples/connection_pool.cpp

@@ -18,35 +18,41 @@ int main(int argc, char **argv) {
         return 1;
     }
 
-    // Ozo perform all IO using Boost.Asio, so first thing we need to do is setup asio::io_context
+    // Ozo perform all IO using Boost.Asio, so the first thing we need to do is to setup asio::io_context
     asio::io_context io;
 
-    // To make a request we need to make a ConnectionSource. It knows how to connect to database using
-    // connection string. See https://www.postgresql.org/docs/9.4/static/libpq-connect.html#LIBPQ-CONNSTRING
-    // how to make a connection string.
-    ozo::connection_info<> connection_info(argv[1]);
+    //! [Creating Connection Pool]
+
+    // To make a connection to a database we need to make a ConnectionSource.
+    auto connection_info = ozo::make_connection_info(argv[1]);
 
-    // Conneciton pool allows to store open connection and reuse them to avoid connect operation for each
-    // request. It supports asynchronous request for connections using callbacks queue with optional capacity
-    // limit and wait timeout. Also connection closes when there is no usage for more than idle timeout.
     ozo::connection_pool_config connection_pool_config;
+
     // Maximum limit for number of stored connections
     connection_pool_config.capacity = 1;
     // Maximum limit for number of waiting requests for connection
     connection_pool_config.queue_capacity = 10;
     // Maximum time duration to store unused open connection
     connection_pool_config.idle_timeout = std::chrono::seconds(60);
+
+    // Creating connection pool from connection_info as the underlying ConnectionSource
     auto connection_pool = ozo::make_connection_pool(connection_info, connection_pool_config);
+    //! [Creating Connection Pool]
 
     const auto coroutine = [&] (asio::yield_context yield) {
+
+        //! [Creating Connection Provider]
+
         // The next step is bind asio::io_context with ConnectionSource to setup executor for all
         // callbacks. Default connection is a ConnectionProvider. If there is some problem with network
-        // or database we don't want to wait indefinetely, so we establish connect timeout. If there is
+        // or database we don't want to wait indefinitely, so we establish connect timeout. If there is
         // no available connection in the connection pool we also want to wait within finite time duration.
         ozo::connection_pool_timeouts timeouts;
         timeouts.connect = std::chrono::seconds(1);
         timeouts.queue = std::chrono::seconds(1);
+
         const auto connector = ozo::make_connector(connection_pool, io, timeouts);
+        //! [Creating Connection Provider]
 
         // Request result is always set of rows. Client should take care of output object lifetime.
         ozo::rows_of<int> result;