Skip to content

Commit 1781cc1

Browse files
victorbvictorb
committed
Final api docs changes
1 parent 72d2fff commit 1781cc1

File tree

6 files changed

+237
-191
lines changed

6 files changed

+237
-191
lines changed

‎.npmignore

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,4 +26,5 @@ build/Release
2626
# https://www.npmjs.org/doc/misc/npm-faq.html#should-i-check-my-node_modules-folder-into-git
2727
node_modules
2828

29-
test
29+
test
30+
docs

‎README.md

Lines changed: 1 addition & 140 deletions
Original file line numberDiff line numberDiff line change
@@ -118,146 +118,7 @@ $ node
118118

119119
## API
120120

121-
```js
122-
const multiaddr = require('multiaddr')
123-
```
124-
125-
### Create
126-
127-
#### const addr = multiaddr(str)
128-
129-
Creates a multiaddress from a string (e.g. `/ip4/127.0.0.1/udp/1234`).
130-
131-
#### const addr = multiaddr(buf)
132-
133-
Creates a multiaddress from another multiaddress' raw bytes.
134-
135-
#### addr.buffer
136-
137-
The raw bytes representing this multiaddress.
138-
139-
#### addr.toString()
140-
141-
The multiaddress in string format (e.g. `/ip4/127.0.0.1/udp/1234`).
142-
143-
### Protocols
144-
145-
#### addr.protoCodes()
146-
147-
Returns the codes of the protocols in the multiaddress, in left-to-right order.
148-
149-
```js
150-
addr.protoCodes()
151-
// [4, 6]
152-
```
153-
154-
#### addr.protoNames()
155-
156-
Returns the names of the protocols in the multiaddress, in left-to-right order.
157-
158-
```js
159-
addr.protoNames()
160-
// ['ip4', 'tcp']
161-
```
162-
163-
#### addr.protos()
164-
165-
Returns description objects of the protocols in the multiaddress, in left-to-right order.
166-
167-
```js
168-
addr.protos()
169-
// [
170-
// { code: 4, name: 'ip4', size: 32},
171-
// { code: 17, name: 'udp', size: 16}
172-
// ]
173-
```
174-
175-
Each object contains the protocol code, protocol name, and the size of its
176-
address space in bits.
177-
178-
### Node-Friendly Addresses
179-
180-
Utility functions for getting NodeJS-friendly address information from a
181-
multiaddress.
182-
183-
#### addr.nodeAddress()
184-
185-
Returns a NodeJS-friendly object describing the left-most address in the
186-
multiaddress.
187-
188-
```js
189-
addr.nodeAddress()
190-
// { family: "IPv4", port:1234, address: "127.0.0.1" }
191-
```
192-
193-
Note that protocol information is left out: in Node (and most network systems)
194-
the protocol is unknowable given only the address.
195-
196-
#### addr.fromNodeAddress(addr)
197-
198-
Constructs a multiaddress, given a NodeJS-friendly address object and a protocol.
199-
200-
```js
201-
addr.fromNodeAddress({family: "IPv4", port:1234, address: "127.0.0.1"}, 'udp')
202-
// <Multiaddr /ip4/127.0.0.1/udp/1234>
203-
```
204-
205-
#### addr.fromStupidString(str)
206-
207-
Returns a multiaddress, given a URI in the format `<proto><IPv>://<IP
208-
Addr>[:<proto port>]`
209-
210-
```js
211-
addr = multiaddr.fromStupidString("udp4://127.0.0.1:1234")
212-
// <Multiaddr /ip4/127.0.0.1/udp/1234>
213-
```
214-
215-
*NOT IMPLEMENTED*
216-
217-
#### addr.toStupidString()
218-
219-
*NOT IMPLEMENTED*
220-
221-
### En/decapsulate
222-
223-
#### addr.encapsulate(str)
224-
225-
Returns a new multiaddress that encapsulates `addr` in a new protocol string,
226-
`str`.
227-
228-
```js
229-
addr.encapsulate('/sctp/5678')
230-
// <Multiaddr /ip4/127.0.0.1/udp/1234/sctp/5678>
231-
```
232-
233-
#### addr.decapsulate(str)
234-
235-
Returns a new multiaddress with the right-most protocol string `str` removed.
236-
237-
```js
238-
multiaddress('/ip4/127.0.0.1/udp/1234').decapsulate('/udp')
239-
// <Multiaddr /ip4/127.0.0.1>
240-
```
241-
242-
### Tunneling
243-
244-
Given these encapsulation/decapsulate tools, multiaddresses lend
245-
themselves to expressing tunnels very nicely:
246-
247-
```js
248-
const printer = multiaddr('/ip4/192.168.0.13/tcp/80')
249-
250-
const proxy = multiaddr('/ip4/10.20.30.40/tcp/443')
251-
252-
const printerOverProxy = proxy.encapsulate(printer)
253-
// <Multiaddr /ip4/10.20.30.40/tcp/443/ip4/192.168.0.13/tcp/80>
254-
```
255-
256-
### Misc
257-
258-
#### `multiaddr.isMultiaddr(addr)`
259-
260-
Returns `true` if the passed in `addr` is a valid `multiaddr`.
121+
TODO: Moved to API-docs, insert link here
261122

262123
## Maintainers
263124

‎documentation.yml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
toc:
2+
- name: Introduction
3+
file: intro.md

‎intro.md

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
JavaScript implementation of [Multiaddr](https://github.com/multiformats/multiaddr).
2+
3+
## What is multiaddr?
4+
5+
Multiaddr is a standard way to represent addresses that:
6+
- Support any standard network protocols.
7+
- Self-describe (include protocols).
8+
- Have a binary packed format.
9+
- Have a nice string representation.
10+
- Encapsulate well.
11+
12+
You can read more about what Multiaddr is in the language-independent Github repository:
13+
https://github.com/multiformats/multiaddr
14+
15+
Multiaddr is a part of a group of values called [Multiformats](https://github.com/multiformats/multiformats)
16+
17+
## Example
18+
19+
```js
20+
var Multiaddr = require('multiaddr')
21+
22+
var home = new Multiaddr('/ip4/127.0.0.1/tcp/80')
23+
// <Multiaddr 047f000001060050 - /ip4/127.0.0.1/tcp/80>
24+
25+
home.buffer
26+
// <Buffer 04 7f 00 00 01 06 00 50>
27+
28+
home.toString()
29+
// '/ip4/127.0.0.1/tcp/80'
30+
31+
home.protos()
32+
// [ { code: 4, size: 32, name: 'ip4' },
33+
// { code: 6, size: 16, name: 'tcp' } ]
34+
35+
home.nodeAddress()
36+
// { family: 'IPv4', address: '127.0.0.1', port: '80' }
37+
38+
var proxy = new Multiaddr('/ip4/192.168.2.1/tcp/3128')
39+
// <Multiaddr 04c0a80201060c38 - /ip4/192.168.2.1/tcp/3128>
40+
41+
var full = proxy.encapsulate(home)
42+
// <Multiaddr 04c0a80201060c38047f000001060050 - /ip4/192.168.2.1/tcp/3128/ip4/127.0.0.1/tcp/80>
43+
44+
full.toString()
45+
// '/ip4/192.168.2.1/tcp/3128/ip4/127.0.0.1/tcp/80'
46+
```
47+
48+
## Installation
49+
50+
### npm
51+
52+
```sh
53+
> npm install multiaddr
54+
```
55+
56+
## Setup
57+
58+
### Node.js
59+
60+
```js
61+
var Multiaddr = require('multiaddr')
62+
```
63+
64+
### Browser: Browserify, Webpack, other bundlers
65+
66+
The code published to npm that gets loaded on require is in fact a ES5
67+
transpiled version with the right shims added. This means that you can require
68+
it and use with your favourite bundler without having to adjust asset management
69+
process.
70+
71+
```js
72+
var Multiaddr = require('multiaddr')
73+
```
74+
75+
### Browser: `<script>` Tag
76+
77+
Loading this module through a script tag will make the `Multiaddr` obj available in
78+
the global namespace.
79+
80+
```html
81+
<script src="https://unpkg.com/multiaddr/dist/index.min.js"></script>
82+
<!-- OR -->
83+
<script src="https://unpkg.com/multiaddr/dist/index.js"></script>
84+
```

‎package.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@
4444
"xtend": "^4.0.1"
4545
},
4646
"devDependencies": {
47-
"aegir": "^9.1.2",
47+
"aegir": "^9.2.0",
4848
"buffer-loader": "0.0.1",
4949
"chai": "^3.5.0",
5050
"pre-commit": "^1.1.3"

0 commit comments

Comments
 (0)