Add documentation to methods

Author: Philippe Masset

Request.js

@@ -2,7 +2,17 @@
  * Interface to send requests – thin wrapper around fetch()
  *
  * send, get and post return a Promise that resolves with a Response object
- * from which can be retrieved Body's contents.
+ * from which can be retrieved Body's contents. They all receive the same params:
+ *
+ * @param {string} url - relative URL of the API endpoint, e.g. 'updates/create.json'
+ * @param {object} [data] - any piece of data to send alongside the request
+ * @param {object} [settings] - any additional options to pass to GlobalFetch.fetch()
+ *
+ * Note: This util encodes data according to the multipart/form-data type, since that's
+ * what most of our current endpoints expect, and it plays well with PHP. For newer
+ * endpoints, esp. Node ones, it might make more sense to JSON.stringify() the data object
+ * and pass it as a string through settings.body, and JSON.parse() that payload on
+ * the server. Additions welcome!
  */
 
 class Request {
@@ -51,13 +61,15 @@ class Request {
 
 /**
  * Split non-primitive values into primitive chunks with formatted keys to be used
- * with FormData.append
+ * with FormData.append()
  *
- * data is an array of primitives, arrays and objects
+ * @param {object} [data] - map of primitives, arrays and objects
  *
- * Example:
+ * E.g.:
  * formatDataPieces({ values: [{ a: 'a', b: 'b' }] })
  * => [ ['values[0][a]', 'a'], ['values[0][b]', 'b'] ]
+ *
+ * TODO: Add tests
  */
 function formatDataPieces(data) {
   const dataPieces = [];