Merge pull request #2799 from ethereum/documentation/web3-module-example

Module API documentation improved
web3 · May 8, 2019 · 16a12b1 · 16a12b1
2 parents cf5a8d8 + cecca9f
commit 16a12b1
Show file tree

Hide file tree

Showing 2 changed files with 95 additions and 0 deletions.
diff --git a/docs/web3-core.rst b/docs/web3-core.rst
@@ -22,6 +22,28 @@ The ``AbstractWeb3Module`` does have the following constructor parameters:
 - ``methodFactory`` - ``AbstractMethodFactory`` The :ref:`AbstractMethodFactory <web3-abstract-method-factory>` will be used in the module proxy for the JSON-RPC method calls. (optional)
 - ``net`` - ``net.Socket`` The ``net.Socket`` object of the NodeJS net module. (optional)
 
+-------
+Example
+-------
+
+.. code-block:: javascript
+
+    import {AbstractWeb3Module} from 'web3-core';
+
+    class Example extends AbstractWeb3Module {
+        /**
+         * @param {AbstractSocketProvider|HttpProvider|CustomProvider|String} provider
+         * @param {AbstractMethodFactory} methodFactory
+         * @param {Web3ModuleOptions} options
+         * @param {Net.Socket} nodeNet
+         *
+         * @constructor
+         */
+        constructor(provider, net, methodFactory, options) {
+            super(provider, net, methodFactory, options;
+        }
+    }
+
 
 Interface of the ``AbstractWeb3Module`` class:
 

diff --git a/docs/web3-module.rst b/docs/web3-module.rst
@@ -20,3 +20,76 @@ These are the core modules which are providing all the classes for the Web3 Modu
 - :ref:`web3-core-subscriptions <web3-core-subscriptions>`
 - :ref:`Contract <web3-module-contract>`
 
+-------
+Example
+-------
+
+.. code-block:: javascript
+
+    import * as Utils from 'web3-utils';
+    import {formatters} from 'web3-core-formatters';
+    import {AbstractWeb3Module} from 'web3-core';
+    import {AbstractMethodFactory, GetBlockByNumberMethod, AbstractMethod} from 'web3-core-method';
+
+    class MethodFactory extends AbstractMethodFactory {
+        /**
+         * @param {Utils} utils
+         * @param {Object} formatters
+         *
+         * @constructor
+         */
+        constructor(utils, formatters) {
+            super(utils, formatters);
+
+            this.methods = {
+                getBlockByNumber: GetBlockByNumberMethod
+            };
+        }
+    }
+
+    class Example extends AbstractWeb3Module {
+        /**
+         * @param {AbstractSocketProvider|HttpProvider|CustomProvider|String} provider
+         * @param {Web3ModuleOptions} options
+         * @param {Net.Socket} nodeNet
+         *
+         * @constructor
+         */
+        constructor(provider, net, options) {
+            super(provider, net, new MethodFactory(Utils, formatters), options;
+        }
+
+        sign() {
+            const method = new AbstractMethod('eth_sign', 2, utils, formatters, this);
+            method.setArguments(arguments)
+
+            return method.execute();
+        }
+
+        logs(options) {
+            return new LogSubscription(
+              options,
+              Utils,
+              formatters,
+              this,
+              new GetPastLogsMethod(Utils, formatters, this)
+            );
+        }
+    }
+
+    const example = new Example(provider, net, options);
+
+    example.sign('0x0', 'message').then(console.log);
+    // > "response"
+
+    example.sign('0x0', 'message', (error, response) => {
+        console.log(response);
+    };
+    // > "response"
+
+    const block = example.getBlockByNumber(1).then(console.log);
+    // > {}
+
+    example.logs(options).subscribe(console.log);
+    > {}
+