Merge pull request #2644 from ethereum/docs/improvements

Documentation updated

docs/callbacks-promises-events.rst

@@ -12,11 +12,11 @@ we provide multiple ways to act on asynchronous functions.
 Most web3.js objects allow a callback as the last parameter, as well as returning promises to chain functions.
 
 Ethereum as a blockchain has different levels of finality and therefore needs to return multiple "stages" of an action.
-To cope with requirement we return a "promiEvent" for functions like ``web3.eth.sendTransaction`` or contract methods.
-This "promiEvent" is a promise combined with an event emitter to allow acting on different stages of action on the blockchain, like a transaction.
+To cope with requirement we return a "PromiEvent" for functions like :ref:`web3.eth.sendTransaction <eth-sendtransaction-return>` or contract methods.
+These stages are encapsulated into a "PromiEvent", which combines a promise with an event emitter.
+The event emitter fires an event for each of the finality stages.
 
-PromiEvents work like a normal promises with added ``on``, ``once`` and ``off`` functions.
-This way developers can watch for additional events like on "receipt" or "transactionHash".
+An example of a function that benefits from a PromiEvent is the :ref:`web3.eth.sendTransaction <eth-sendtransaction-return>` method.
 
 .. code-block:: javascript
 

docs/conf.py

@@ -49,8 +49,8 @@
 
 # General information about the project.
 project = u'web3.js'
-copyright = u'2016, Ethereum'
-author = u'Fabian Vogelsteller, Marek Kotewicz, Jeffrey Wilcke, Marian Oancea, Gav Wood'
+copyright = u'2019, Ethereum'
+author = u'Samuel Furter, Fabian Vogelsteller, Marek Kotewicz, Jeffrey Wilcke, Marian Oancea, Gav Wood'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the

docs/getting-started.rst

@@ -1,16 +1,15 @@
-
 .. include:: include_announcement.rst
 
 ===============
 Getting Started
 ===============
 
-The web3.js library is a collection of modules which contain specific functionality for the ethereum ecosystem.
+The web3.js library is a collection of modules which contain specific functionality for the Ethereum ecosystem.
 
-- The ``web3-eth`` is for the ethereum blockchain and smart contracts
+- The ``web3-eth`` is for the Ethereum blockchain and smart contracts
 - The ``web3-shh`` is for the whisper protocol to communicate p2p and broadcast
 - The ``web3-bzz`` is for the swarm protocol, the decentralized file storage
-- The ``web3-utils`` contains useful helper functions for Dapp developers.
+- The ``web3-utils`` contains useful helper functions for DApp developers.
 
 
 .. _adding-web3:
@@ -19,23 +18,33 @@ Adding web3.js
 ==============
 
 .. index:: npm
-.. index:: bower
-.. index:: meteor
 
 First you need to get web3.js into your project. This can be done using the following methods:
 
 - npm: ``npm install web3``
-- meteor: ``meteor add ethereum:web3``
-- pure js: link the ``dist/web3.min.js``
 
 After that you need to create a web3 instance and set a provider.
-Ethereum supported Browsers like Mist or MetaMask will have a ``ethereumProvider`` or ``web3.currentProvider`` available. For  web3.js, check ``Web3.givenProvider``.
-If this property is ``null`` you should connect to a remote/local node.
+A Ethereum compatible browser will have a ``window.ethereum`` or ``web3.currentProvider`` available.
+For  web3.js, check ``Web3.givenProvider``. If this property is ``null`` you should connect to your own local or remote node.
 
 .. code-block:: javascript
 
     // in node.js use: const Web3 = require('web3');
 
-    const web3 = new Web3(Web3.givenProvider || "ws://localhost:8546");
+    // use the given Provider, e.g in the browser with Metamask, or instantiate a new websocket provider
+    const web3 = new Web3(Web3.givenProvider || 'ws://localhost:8546', null, {});
+
+    // or
+    const web3 = new Web3(Web3.givenProvider || new Web3.providers.WebsocketProvider('ws://localhost:8546'), null, {});
+
+    // Using the IPC provider in node.js
+    const net = require('net');
+
+    const web3 = new Web3('/Users/myuser/Library/Ethereum/geth.ipc', net, {}); // mac os path
+    // or
+    const web3 = new Web3(new Web3.providers.IpcProvider('/Users/myuser/Library/Ethereum/geth.ipc', net, {})); // mac os path
+    // on windows the path is: '\\\\.\\pipe\\geth.ipc'
+    // on linux the path is: '/users/myuser/.ethereum/geth.ipc'
+
 
 That's it! now you can use the ``web3`` object.

docs/glossary.rst

@@ -5,19 +5,6 @@
 Glossary
 ========
 
-
-
-.. _glossary-json-interface:
-
-------------------------------------------------------------------------------
-
-json interface
-=====================
-
-The json interface is a json object describing the `Application Binary Interface (ABI) <https://github.com/ethereum/wiki/wiki/Ethereum-Contract-ABI>`_ for an Ethereum smart contract.
-
-Using this json interface web3.js is able to create JavaScript object representing the smart contract and its methods and events using the :ref:`web3.eth.Contract object <eth-contract>`.
-
 -------
 Specification
 -------

docs/include_package-core.rst

@@ -4,6 +4,8 @@ options
 An Web3 module does provide several options for configuring the transaction confirmation worklfow or for defining default values.
 These are the currently available option properties on a Web3 module:
 
+.. _web3-module-options:
+
 --------------
 Module Options
 --------------
@@ -43,7 +45,7 @@ Example
         transactionSigner: new CustomTransactionSigner()
     }
 
-    const web3 = new Web3('http://localhost:8545', options);
+    const web3 = new Web3('http://localhost:8545', null, options);
 
 ------------------------------------------------------------------------------
 
@@ -59,13 +61,30 @@ defaultBlock
     web3.shh.defaultBlock
     ...
 
-The default block which will be used for a requests.
+The default block is used for all methods which have a block parameter.
+You can override it by passing the block parameter if a block is required.
+
+Example:
+
+- :ref:`web3.eth.getBalance() <eth-getbalance>`
+- :ref:`web3.eth.getCode() <eth-getcode>`
+- :ref:`web3.eth.getTransactionCount() <eth-gettransactioncount>`
+- :ref:`web3.eth.getStorageAt() <eth-getstorageat>`
+- :ref:`web3.eth.call() <eth-call>`
+- :ref:`new web3.eth.Contract() -> myContract.methods.myMethod().call() <contract-call>`
 
 -------
 Returns
 -------
 
-``string|number``: The current value of the defaultBlock property.
+The ``defaultBlock`` property can return the following values:
+
+- ``Number``: A block number
+- ``"genesis"`` - ``String``: The genesis block
+- ``"latest"`` - ``String``: The latest block (current head of the blockchain)
+- ``"pending"`` - ``String``: The currently mined block (including pending transactions)
+
+Default is ``"latest"``
 
 ------------------------------------------------------------------------------
 
@@ -81,13 +100,13 @@ defaultAccount
     web3.shh.defaultAccount
     ...
 
-The default account which will be used for a requests.
+This default address is used as the default ``"from"`` property, if no ``"from"`` property is specified.
 
 -------
 Returns
 -------
 
-``null|string``: The current value of the defaultAccount property.
+``String`` - 20 Bytes: Any Ethereum address. You need to have the private key for that address in your node or keystore. (Default is ``undefined``)
 
 ------------------------------------------------------------------------------
 
@@ -148,8 +167,8 @@ transactionBlockTimeout
     web3.shh.transactionBlockTimeout
     ...
 
-This can be used with a socket provider and defines the number of blocks until the PromiEvent
-rejects with a timeout error.
+The ``transactionBlockTimeout`` will be used over a socket based connection. This option does define the amount of new blocks it should wait until the first confirmation happens.
+This means the PromiEvent rejects with a timeout error when the timeout got exceeded.
 
 
 -------
@@ -173,7 +192,6 @@ transactionConfirmationBlocks
     ...
 
 This defines the number of blocks it requires until a transaction will be handled as confirmed.
-The PromiEvent will resolve with the desired receipt when enough confirmations happened.
 
 
 -------
@@ -197,8 +215,8 @@ transactionPollingTimeout
     web3.shh.transactionPollingTimeout
     ...
 
-This defines the polling cycles amount when you send a transaction with the HttpProvider.
-The PromiEvent rejects with a timeout error when the timeout got exceeded. (1 cycle == 1sec.).
+The ``transactionPollingTimeout``  will be used over a HTTP connection.
+This option does define the amount of polls (each second) it should wait until the first confirmation happens.
 
 
 -------
@@ -371,7 +389,7 @@ Will return the given provider by the (browser) environment, otherwise ``null``.
 Returns
 -------
 
-``Object``: The given provider set or ``null``;
+``Object``: The given provider set or ``false``.
 
 -------
 Example
@@ -396,22 +414,22 @@ currentProvider
     web3.bzz.currentProvider
     ...
 
-Will return the current provider, otherwise ``null``.
+Will return the current provider.
 
 
 -------
 Returns
 -------
 
-``Object``: The current provider set or ``null``;
+``Object``: The current provider set.
 
 -------
 Example
 -------
 
 .. code-block:: javascript
 
-    if(!web3.currentProvider) {
+    if (!web3.currentProvider) {
         web3.setProvider('http://localhost:8545');
     }
 
@@ -453,6 +471,6 @@ Example
     const contract = new web3.eth.Contract(abi, address);
 
     const batch = new web3.BatchRequest();
-    batch.add(web3.eth.getBalance.request('0x0000000000000000000000000000000000000000', 'latest', callback));
-    batch.add(contract.methods.balance(address).call.request({from: '0x0000000000000000000000000000000000000000'}, callback2));
-    batch.execute();
+    batch.add(web3.eth.getBalance.request('0x0000000000000000000000000000000000000000', 'latest'));
+    batch.add(contract.methods.balance(address).call.request({from: '0x0000000000000000000000000000000000000000'}));
+    batch.execute().then(...);

docs/include_package-net.rst

@@ -30,8 +30,7 @@ Example
 
 .. code-block:: javascript
 
-    web3.eth.net.getId()
-    .then(console.log);
+    web3.eth.net.getId().then(console.log);
     > 1
 
 ------------------------------------------------------------------------------
@@ -65,8 +64,7 @@ Example
 
 .. code-block:: javascript
 
-    web3.eth.isListening()
-    .then(console.log);
+    web3.eth.isListening().then(console.log);
     > true
 
 ------------------------------------------------------------------------------
@@ -100,6 +98,5 @@ Example
 
 .. code-block:: javascript
 
-    web3.eth.getPeerCount()
-    .then(console.log);
+    web3.eth.getPeerCount().then(console.log);
     > 25

docs/index.rst

@@ -5,8 +5,8 @@
 web3.js - Ethereum JavaScript API
 =================================
 
-web3.js is a collection of libraries which allow you to interact with a local or remote ethereum node,
-using a HTTP or IPC connection.
+web3.js is a collection of libraries which allow you to interact with a local or remote Ethereum node,
+using an HTTP, WebSocket or IPC connection.
 
 The following documentation will guide you through :ref:`installing and running web3.js <adding-web3>`,
 as well as providing a :ref:`API reference documentation <#id1>` with examples.

docs/web3-bzz.rst

@@ -18,15 +18,15 @@ For more see the `Swarm Docs <http://swarm-guide.readthedocs.io/en/latest/>`_.
     import Web3 from 'web3';
     import {Bzz} from 'web3-bzz';
 
-    // will autodetect if the "ethereum" object is present and will either connect to the local swarm node, or the swarm-gateways.net.
+    // will autodetect if a provider is present and will either connect to the local swarm node, or the swarm-gateways.net.
     // Optional you can give your own provider URL; If no provider URL is given it will use "http://swarm-gateways.net"
     const bzz = new Bzz(Web3.givenProvider || 'http://swarm-gateways.net');
 
 
     // or using the web3 umbrella package
     const web3 = new Web3(Web3.givenProvider || 'ws://some.local-or-remote.node:8546');
 
-    // -> web3.bzz.currentProvider // if Web3.givenProvider was an ethereum provider it will set: "http://localhost:8500" otherwise it will set: "http://swarm-gateways.net"
+    // -> web3.bzz.currentProvider // if Web3.givenProvider was an Ethereum provider it will set: "http://localhost:8500" otherwise it will set: "http://swarm-gateways.net"
 
 
 ------------------------------------------------------------------------------

docs/web3-eth-abi.rst

@@ -7,7 +7,7 @@ web3.eth.abi
 =========
 
 The ``web3-eth-abi`` package allows you to de- and encode parameters from a ABI (Application Binary Interface).
-This will be used for function calls to the EVM (Ethereum Virtual Machine).
+This will be used for calling functions of a deployed smart-contract.
 
 .. code-block:: javascript
 
@@ -19,9 +19,9 @@ This will be used for function calls to the EVM (Ethereum Virtual Machine).
     // or using the web3 umbrella package
 
 
-    import {Web3} from 'web3';
+    import Web3 from 'web3';
 
-    const web3 = new Web3(Web3.givenProvider || 'ws://some.local-or-remote.node:8546', options);
+    const web3 = new Web3(Web3.givenProvider || 'ws://some.local-or-remote.node:8546', null, options);
     // -> web3.eth.abi
 
 

docs/web3-eth-accounts.rst

@@ -8,19 +8,15 @@ web3.eth.accounts
 
 The ``web3.eth.accounts`` contains functions to generate Ethereum accounts and sign transactions and data.
 
-.. note:: This package has NOT been audited and might potentially be unsafe. Take precautions to clear memory properly, store the private keys safely, and test transaction receiving and sending functionality properly before using in production!
-
-To use this package standalone use:
-
+.. note:: This package got NOT audited until now. Take precautions to clear memory properly, store the private keys safely, and test transaction receiving and sending functionality properly before using in production!
 
 .. code-block:: javascript
 
-    import {Accounts} from 'web3-eth-accounts;
+    import {Accounts} from 'web3-eth-accounts';
 
     // Passing in the eth or web3 package is necessary to allow retrieving chainId, gasPrice and nonce automatically
     // for accounts.signTransaction().
-    const accounts = new Accounts('ws://localhost:8546', options);
-
+    const accounts = new Accounts('ws://localhost:8546', null, options);
 
 
 ------------------------------------------------------------------------------