Add ipfs.files.add documentation.

Author: hackergrrl

README.md

@@ -25,7 +25,7 @@ interface-ipfs-core API.
 
 ![](/img/badge.png)
 
-# How to use the battery tests
+# How to use the battery of tests
 
 ## Node.js
 
@@ -55,6 +55,86 @@ test.all(common)
 
 A valid (read: that follows this interface) IPFS core implementation, must expose the following API.
 
+## Files
+
+### `add`
+
+> Add files and data to IPFS.
+
+##### `Go` **WIP**
+
+##### `JavaScript` - ipfs.files.add(data, [callback])
+
+Where `data` may be
+
+- an array of objects, each of the form
+```js
+{
+  path: '/tmp/myfile.txt',
+  content: (Buffer or Readable stream)
+}
+```
+- a `Buffer` instance
+- a `Readable` stream
+
+`callback` must follow `function (err, res) {}` signature, where `err` is an
+error if the operation was not successful. `res` will be an array of
+[DAGNode][]s.
+
+If no `callback` is passed, a promise is returned.
+
+```js
+var files = [
+  {
+    path: '/tmp/myfile.txt',
+    content: fs.createReadStream('/tmp/myfile.txt')
+  }
+]
+ipfs.files.add(files, function (err, dagNodes) {
+  // 'res' will be an array of DAGNodes
+})
+```
+
+
+### `createAddStream`
+
+> Add files and data to IPFS using a transform stream.
+
+##### `Go` **WIP**
+
+##### `JavaScript` - ipfs.files.createAddStream([callback])
+
+Provides a Transform stream, where objects can be written of the forms
+
+```js
+{
+  path: '/tmp/myfile.txt',
+  content: (Buffer or Readable stream)
+}
+```
+
+`callback` must follow `function (err, stream) {}` signature, where `err` is an
+error if the operation was not successful. `stream` will be a Transform stream,
+to which tuples like the above two object formats can be written and [DAGNode][]
+objects will be outputted.
+
+If no `callback` is passed, a promise is returned.
+
+```js
+ipfs.files.createAddStream(function (err, stream) {
+  stream.on('data', function (dagNode) {
+    // ...
+  })
+
+  stream.write({path: <path to file>, content: <buffer or readable stream>})
+  // write as many as you want
+
+  stream.end()
+})
+```
+
+
+
 ## Object
 
 ### `object.new`