Skip to content

Commit

Permalink
Docs: Review current documentation (#204)
Browse files Browse the repository at this point in the history
  • Loading branch information
@0xGabi
0xGabi authored Aug 14, 2020
1 parent 13c57df commit d1349b5
Show file tree
Hide file tree
Showing 5 changed files with 25 additions and 26 deletions.
23 changes: 14 additions & 9 deletions docs/advanced/app-connectors.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,13 +10,18 @@ The connectors are composed of a root project which implements a base connector

### The connector

The `src` folder contains a connector implementation for The Graph which uses `@aragon/connect-thegraph` to perform GraphQL queries, parse them, and present the result in the form of entity objects compatible with the `@aragon/connect` API.
We are using and recommend the following structure to implement app connectors.

Use `index.ts` to pick which entities and objects are exposed to other packages.
The `src` folder contains:

In `connector.ts`, add functions that the entities of your connector will use. For example, the `Vote` entity will call its `castsForVote(...): Promise<Cast[]>` function. These functions all follow the same structure of \(1\) performing a query, \(2\) parsing the results of a query, and \(3\) wrapping and returning the results in the appropriate entity.
- `models` folder: objects compatible with the `@aragon/connect` API. This is what the consumers of your app connector are going to interact with.
- `thegraph` folder: a connector implementation for The Graph which uses `@aragon/connect-thegraph` to perform GraphQL queries, parse them and present the result in the form of models objects. This part is only used internally, and `connector.ts` contains the methods responsible to fetch the app data from The Graph.

Each of the steps described above is separated in the `entities`, `parsers`, and `queries` folders for clarity.
Use `index.ts` to pick which models and objects are exposed to other packages.

Use `connect.ts` to create the connector logic [using `createAppConnector()`](#create-the-connector) from `'@aragon/connect-core'`.

In `thegraph/connector.ts` (assuming your connector is using The Graph), add functions that the models of your connector will use. For example, the `Vote` model of `@aragon/connect-voting` [will call its `castsForVote(...): Promise<Cast[]>` function](https://github.com/aragon/connect/blob/12dec7e5147220d29fb960bff01ff95e9ccca1bf/packages/connect-voting/src/models/Vote.ts#L39). These functions all follow the same structure of \(1\) performing a query, \(2\) parsing the results of a query, and \(3\) wrapping and returning the results in the appropriate model.

Queries are defined using [`graphql-tag`](https://github.com/apollographql/graphql-tag), which allows using fragments. [Fragments](https://graphql.org/learn/queries/#fragments) are useful when your queries become complicated and you want to reuse "fragments" of queries.

Expand Down Expand Up @@ -64,7 +69,7 @@ Following the same example, this is how the connector for the Voting app is impl

```js
import { createAppConnector } from '@aragon/connect-core'
import Voting from './entities/Voting'
import Voting from './models/Voting'
import VotingConnectorTheGraph, {
subgraphUrlFromChainId,
} from './thegraph/connector'
Expand All @@ -77,7 +82,7 @@ export default createAppConnector(
)
}

return new MyAppConnector(
return new Voting(
new VotingConnectorTheGraph(
config.subgraphUrl ?? subgraphUrlFromChainId(network.chainId),
verbose
Expand All @@ -88,9 +93,9 @@ export default createAppConnector(
)
```
#### `createAppConnector\(callback\)`
#### createAppConnector\(callback\)
Here are the parameters passed to the `createAppConnector()` callback:
Parameters passed to the `createAppConnector()` callback:
| Name | Type | Description |
| ----------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
Expand All @@ -102,7 +107,7 @@ Here are the parameters passed to the `createAppConnector()` callback:
#### appConnect\(app, connector\)
The function returned by `createAppConnector()`, called by app authors, takes these parameters:
The function returned by `createAppConnector()`, called by app authors. It takes these parameters:
| Name | Type | Description |
| ----------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
Expand Down
9 changes: 1 addition & 8 deletions docs/api-reference/connect.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,17 +15,10 @@ Connects and returns an `Organization` for `location`.
| `options.network` | [`Networkish`](./types.md#networkish) | The network to connect to. Defaults to `1`. |
| returns | `Promise<Organization>` | An `Organization` instance. |

### Errors

| Type | Description |
| ---------------------- | ------------------------------------------------------ |
| `ConnectionError` | Gets thrown if the connection fails. |
| `OrganizationNotFound` | Gets thrown if the organization doesn’t seem to exist. |

### Example

```javascript
import { connect } from '@aragon/connect'
import connect from '@aragon/connect'

// Connections should get wrapped in a try / catch to capture connection errors
try {
Expand Down
4 changes: 2 additions & 2 deletions docs/api-reference/transaction-intent.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,12 +20,12 @@ This is an easier way to do `TransactionIntent.paths(account, options)[0].transa

### TransactionIntent\#paths\(account, options\)

Get all the possible transaction paths for a given address. This can be useful to let users pick between multiple paths. Otherwise, `TransactionIntent#transactions()` can be called directly.
Get the shortest transaction path for a given address. Note, `TransactionIntent#transactions()` can be called directly.

| Name | Type | Description |
| -------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------- |
| `account` | `String` | The account that will sign the transaction. |
| `options` | `Object` | Options object. |
| `options.as` | `String` | Address of an Aragon organization, or its agent app, through which the paths should get created. |
| `options.path` | `String[]` | An array of address that conform a transaction path, it will be verified without calculating other paths. |
| returns | `Promise<TransactionPath[]>` | Array of all the possible transaction paths. |
| returns | `Promise<TransactionPath>` | Shortest transaction path for the intent. |
2 changes: 1 addition & 1 deletion docs/guides/connect-with-react.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@ This component is required in order to use the provided hooks.
| `connector` | `Connector` or `[String, Object]` or `String` | Accepts a `Connector` instance, and either a string or a tuple for embedded connectors and their config. |
| `options` | `Object` | The optional configuration object. |
| `options.ethereum` | `EthereumProvider` | An [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193) compatible object. |
| `options.network` | [`Networkish`](./types.md#networkish) | The network to connect to. Defaults to `1`. |
| `options.network` | [`Networkish`](../api-reference/types.md#networkish) | The network to connect to. Defaults to `1`. |

### useOrganization()

Expand Down
13 changes: 7 additions & 6 deletions docs/guides/getting-started.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ This guide assumes that you are familiar with the way Aragon organizations work.
This is how to connect to an organization and list its apps:

```javascript
import { connect } from '@aragon/connect'
import connect from '@aragon/connect'

// Initiates the connection to an organization
const org = await connect('example.aragonid.eth', 'thegraph')
Expand All @@ -38,6 +38,7 @@ A connector can be of two types: **organization** or **app**, to fetch data from
Aragon Connect consists of a few parts:

- `@aragon/connect`: this is the main library. It provides the main features to connect and interact with organizations, and includes the basic organization connectors.
- `@aragon/connect-finance`: an app connector for fetching data from the Finance app.
- `@aragon/connect-voting`: an app connector for fetching data from the Voting app.
- `@aragon/connect-tokens`: an app connector for fetching data from the Tokens app.
- Additional app connectors published by individual app authors
Expand All @@ -58,9 +59,10 @@ You can now import it:
import connect from '@aragon/connect'
```

If you want to interact with the Voting or the Tokens app, you should also install their respective connectors:
If you want to interact with the Finance, Voting or the Tokens app, you should also install their respective connectors:

```text
yarn add @aragon/connect-finance
yarn add @aragon/connect-voting
yarn add @aragon/connect-tokens
```
Expand Down Expand Up @@ -121,7 +123,7 @@ It is also possible to subscribe to receive data updates as they arrive.
For example, this is how it can be done for the list of apps:

```javascript
import { connect } from '@aragon/connect'
import connect from '@aragon/connect'

const org = await connect('example.aragonid.eth', 'thegraph')

Expand Down Expand Up @@ -168,11 +170,10 @@ Generating a transaction is done in three steps. First, call a method returning
const intent = await org.appIntent(voting, 'vote', [votes[0].id, true, true])
```

Then to retrieve the path you want, pass the account that will be signing the transaction. Aragon Connect will go through the permissions of the organization, and return all possible paths:
Then to retrieve the path you want, pass the account that will be signing the transaction. Aragon Connect will go through the permissions of the organization, and return the shortest path:

```javascript
// The first path is the shortest
const [path] = intent.paths(wallet.account)
const path = intent.paths(wallet.account)
```

Finally, you can sign the different transactions associated to this path. Aragon Connect doesn’t handle any signing itself, but returns an object that is ready to use with the library of your choice: [ethers.js](https://docs.ethers.io/v5/), [Web3.js](https://web3js.readthedocs.io/en/1.0/), or even a [JSON-RPC connection to an Ethereum node](https://eips.ethereum.org/EIPS/eip-1474).
Expand Down

0 comments on commit d1349b5

Please sign in to comment.