jsonrpc: public interfaces are documented

Author: ashtum

example/client/jsonrpc/cpp20.cpp

@@ -95,6 +95,19 @@ co_main(
         << std::setprecision(3) << dec_float(to_int(gas_price)) / dec_float("1e10")
         << " GWEI\n";
 
+    // Get ETH/USD price from a Chainlink oracle
+    auto eth_usd = co_await client[eth_call](
+        {
+            {
+                {"to", "0x5f4ec3df9cbd43714fe2740f5e3616155c5b8419"}, // ETH/USD price feed
+                {"data", "0x50d25bcd"} // latestRoundData() selector
+            },
+            "latest"
+        });
+    std::cout
+        << "ETH/USD:      "
+        << std::fixed << dec_float(to_int(eth_usd)) / dec_float("1e8") << '\n';
+
     // Gracefully close the stream
     auto [ec] = co_await client.async_shutdown(asio::as_tuple);
     if(ec && ec != asio::ssl::error::stream_truncated)
@@ -105,14 +118,15 @@ co_main(
 Sample output:
 
 web3 client:  "erigon/3.0.4/linux-amd64/go1.23.9"
-Block number: 23175159
-Block hash:   "0xd476f0a0dd29be4d63bc737937f6c40b024906f1a864ee38aa1a03f91ce55efd"
-Block size:   87166 Bytes
-Timestamp:    1755606983
-Transactions: 176
+Block number: 23189485
+Block hash:   "0xc42ff6625921df3a09495cbea3353ab6e60167319d2c64cedfdd265b7af0a738"
+Block size:   132074 Bytes
+Timestamp:    1755779639
+Transactions: 259
 Balance:      180774.35501503312 ETH
 Gas estimate: 21000
-Gas price:    0.0337 GWEI
+Gas price:    0.039 GWEI
+ETH/USD:      4280.746
 */
 
 int

example/client/jsonrpc/jsonrpc/any_stream.hpp

@@ -17,6 +17,7 @@
 
 namespace jsonrpc {
 
+/// Interface for a stream that can be used with @ref client.
 class any_stream
 {
 public:

example/client/jsonrpc/jsonrpc/client.hpp

@@ -26,6 +26,7 @@
 
 namespace jsonrpc {
 
+/// A JSON-RPC 2.0 client.
 class client
 {
     std::unique_ptr<any_stream> stream_;
@@ -47,49 +48,70 @@ class client
     using next_layer_type = any_stream;
 
     /// The type of the executor associated with the object.
-    using executor_type = typename next_layer_type::executor_type;
+    using executor_type = typename any_stream::executor_type;
 
+    /** Constructor.
+
+        Constructs a client capable of connecting to
+        an HTTP or HTTPS endpoint.
+    */ 
     client(
         boost::urls::url endpoint,
         const boost::rts::context& rts_ctx,
         boost::asio::any_io_executor exec,
         boost::asio::ssl::context& ssl_ctx);
 
+    /** Constructor.
+
+        Constructs a client using the supplied
+        @ref any_stream instance.
+    */ 
     client(
         boost::urls::url endpoint,
         const boost::rts::context& rts_ctx,
         std::unique_ptr<any_stream> stream);
 
+    /// Get the executor associated with the object.
     executor_type
     get_executor() noexcept
     {
         return stream_->get_executor();
     }
 
+    /// Get a reference to the next layer.
     next_layer_type&
     next_layer() noexcept
     {
         return *stream_;
     }
 
+    /// Get a reference to the next layer.
     next_layer_type const&
     next_layer() const noexcept
     {
         return *stream_;
     }
 
+    /// Return the endpoint that the client is configured with.
     boost::urls::url_view
     endpoint() const noexcept
     {
         return endpoint_;
     }
 
+    /** Return a reference to the fields container of the HTTP
+        request message.
+
+        This function can be used to customize HTTP headers, for
+        example, to add the required credentials.
+    */
     boost::http_proto::fields_base&
     http_fields()
     {
         return req_;
     }
 
+    /// Connect to the endpoint.
     template<
         BOOST_ASIO_COMPLETION_TOKEN_FOR(void(boost::system::error_code))
             CompletionToken = boost::asio::deferred_t>
@@ -103,6 +125,7 @@ class client
                 this);
     }
 
+    /// Shutdown the stream.
     template<
         BOOST_ASIO_COMPLETION_TOKEN_FOR(void(boost::system::error_code))
             CompletionToken = boost::asio::deferred_t>
@@ -119,7 +142,7 @@ class client
     template<typename Signature>
     class invoker;
 
-    /** Calls a remote procedure that takes no parameters.
+    /** Call a remote procedure that takes no parameters.
 
         Instances of this type are returned from @ref operator[].
 
@@ -131,6 +154,14 @@ class client
         using invoker_base::invoker_base;
     public:
 
+        /** Call a remote procedure that takes no parameters.
+
+            The result type depends on the signature of the @ref method object
+            used to instantiate the invoker.
+
+            @param token The completion token used to produce a completion
+            handler, which will be invoked when the call completes.
+        */
         template<
             BOOST_ASIO_COMPLETION_TOKEN_FOR(void(error, Return))
                 CompletionToken BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)>
@@ -145,7 +176,7 @@ class client
         }
     };
 
-    /** Calls a remote procedure with positional parameters (as an array).
+    /** Call a remote procedure with positional parameters (array).
 
         Instances of this type are returned from @ref operator[].
 
@@ -157,6 +188,17 @@ class client
         using invoker_base::invoker_base;
     public:
 
+        /** Call a remote procedure with positional parameters (array).
+
+            The result type depends on the signature of the @ref method object
+            used to instantiate the invoker. 
+
+            @param params A JSON array containing the positional parameters to
+            use when calling the server method.
+
+            @param token The completion token used to produce a completion
+            handler, which will be invoked when the call completes.
+        */
         template<
             BOOST_ASIO_COMPLETION_TOKEN_FOR(void(error, Return))
                 CompletionToken BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)>
@@ -172,7 +214,7 @@ class client
         }
     };
 
-    /** Calls a remote procedure with named parameters (as an object).
+    /** Call a remote procedure with named parameters (object).
 
         Instances of this type are returned from @ref operator[].
 
@@ -184,6 +226,17 @@ class client
         using invoker_base::invoker_base;
     public:
 
+        /** Call a remote procedure with named parameters (object).
+
+            The result type depends on the signature of the @ref method object
+            used to instantiate the invoker. 
+
+            @param params A JSON object containing the named parameters to use
+            when calling the server method.
+
+            @param token The completion token used to produce a completion
+            handler, which will be invoked when the call completes.
+        */
         template<
             BOOST_ASIO_COMPLETION_TOKEN_FOR(void(error, Return))
                 CompletionToken BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)>
@@ -199,6 +252,20 @@ class client
         }
     };
 
+    /** Return an @ref invoker instance that can be used to asynchronously
+        invoke the specified method.
+
+        Example:
+        @code
+        client[method_a]({ "param1", "param2" }, completion_token);
+        @endcode
+
+        @return An @ref invoker capable of asynchronously calling the specified
+        method.
+
+        @param m The @ref method object containing the name and signature of the
+        remote procedure.
+    */
     template<typename Signature>
     invoker<Signature>
     operator[](method<Signature> m) noexcept

example/client/jsonrpc/jsonrpc/error.hpp

@@ -18,6 +18,10 @@
 
 namespace jsonrpc {
 
+/** An error type that encapsulates both an error code
+    and an optional JSON object containing additional error
+    details as provided by the server.
+*/
 class error
 {
     boost::system::error_code ec_;
@@ -43,12 +47,16 @@ class error
         return *this;
     }
 
+    /// Return the error code
     const boost::system::error_code&
     code() const noexcept
     {
         return ec_;
     }
 
+    /** Return an optional JSON object containing additional
+        error details as provided by the server.
+    */
     const boost::json::object&
     object() const noexcept
     {

example/client/jsonrpc/jsonrpc/method.hpp

@@ -14,9 +14,20 @@
 
 namespace jsonrpc {
 
+/** Containin the name and signature of a remote
+    procedure.
+
+    @par Example:
+    @code
+    method<json::string()> web3_clientVersion = "web3_clientVersion";
+    @endcode
+
+    @tparam Signature The signature of the method.
+*/
 template<typename Signature>
 struct method;
 
+/// @copydoc method
 template<typename Return>
 struct method<Return()>
 {
@@ -29,6 +40,7 @@ struct method<Return()>
     }
 };
 
+/// @copydoc method
 template<typename Return, typename Param>
 struct method<Return(Param)>
 {