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,73 @@ 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',
+  stream: fs.createReadStream('/tmp/myfile.txt')
+}
+```
+- an array of objects, each of the form
+```js
+{
+  path: '/tmp/myfile.txt',
+  content: new Buffer('hello')
+}
+```
+- a `Buffer` instance
+- a Readable stream
+
+`callback` must follow `function (err, res) {}` signature, where `err` is an
+error if the operation was not successful. If no value `data` is provided, `res`
+will be a Duplex stream, to which tuples like the above two object formats can
+be written and [DAGNode][] objects will be outputted. Otherwise, `res` will be
+an array of [DAGNode][]s.
+
+If no `callback` is passed, a promise is returned.
+
+```js
+// array in => array out
+var files = [
+  {
+    path: '/tmp/myfile.txt',
+    stream: fs.createReadStream('/tmp/myfile.txt')
+  }
+]
+ipfs.files.add(files, function (err, dagNodes) {
+  // 'res' will be an array of DAGNodes
+})
+```
+
+```js
+// no input => duplex stream out
+ipfs.files.add(function (err, stream) {
+  stream.on('data', function (dagNode) {
+    // ...
+  })
+
+  stream.write({path: <path to file>, stream: <readable stream>})
+  // write as many as you want
+
+  stream.end()
+})
+```
+
+
+
+
 ## Object
 
 ### `object.new`