Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation updated #2644

Merged
merged 26 commits into from
Apr 4, 2019
Merged
Show file tree
Hide file tree
Changes from 12 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions docs/callbacks-promises-events.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
4 changes: 2 additions & 2 deletions docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
31 changes: 20 additions & 11 deletions docs/getting-started.rst
Original file line number Diff line number Diff line change
@@ -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:
Expand All @@ -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 ``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.
nivida marked this conversation as resolved.
Show resolved Hide resolved

.. 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.
14 changes: 7 additions & 7 deletions docs/include_package-core.rst
Original file line number Diff line number Diff line change
Expand Up @@ -371,7 +371,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
Expand All @@ -396,22 +396,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');
}

Expand Down Expand Up @@ -453,6 +453,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(...);
9 changes: 3 additions & 6 deletions docs/include_package-net.rst
Original file line number Diff line number Diff line change
Expand Up @@ -30,8 +30,7 @@ Example

.. code-block:: javascript

web3.eth.net.getId()
.then(console.log);
web3.eth.net.getId().then(console.log);
> 1

------------------------------------------------------------------------------
Expand Down Expand Up @@ -65,8 +64,7 @@ Example

.. code-block:: javascript

web3.eth.isListening()
.then(console.log);
web3.eth.isListening().then(console.log);
> true

------------------------------------------------------------------------------
Expand Down Expand Up @@ -100,6 +98,5 @@ Example

.. code-block:: javascript

web3.eth.getPeerCount()
.then(console.log);
web3.eth.getPeerCount().then(console.log);
> 25
2 changes: 1 addition & 1 deletion docs/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ 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.
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.
Expand Down
4 changes: 2 additions & 2 deletions docs/web3-bzz.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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 an provider is present and will either connect to the local swarm node, or the swarm-gateways.net.
nivida marked this conversation as resolved.
Show resolved Hide resolved
// 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"


------------------------------------------------------------------------------
Expand Down
6 changes: 3 additions & 3 deletions docs/web3-eth-abi.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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 to call functions of a deployed smart-contract.

.. code-block:: javascript

Expand All @@ -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


Expand Down
8 changes: 2 additions & 6 deletions docs/web3-eth-accounts.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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!
nivida marked this conversation as resolved.
Show resolved Hide resolved

.. code-block:: javascript

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);


------------------------------------------------------------------------------
Expand Down
Loading