Improve the "unsupported format" error message

The message was misleading and some users misunderstood it: JSZip doesn't
reject a file because of what the content actually is (json file, mp4
file, etc). It rejects a file because it is not a supported JavaScript
object (usually a plain object containing the buffer, not the buffer
directly).

The new message and the FAQ entry should help clear the
misunderstanding.

Author: dduponchel

documentation/faq.md

@@ -16,3 +16,26 @@ decode the binary content as a text and corrupt it. See
 That happens if you try to handle to much data with the synchronous API. If
 possible, try the asynchronous API, see
 [this page]({{site.baseurl}}/documentation/limitations.html) for more informations.
+
+### Can't read the data of [...]. Is it in a supported JavaScript type ?
+
+Or the old message:
+
+> The data of [...] is in an unsupported format
+
+The method [`file(name, data [,options])`]({{site.baseurl}}/documentation/api_jszip/file_data.html)
+accepts string and binary inputs for `data`.
+
+If you use an unsupported type, an object for example, you will get this error:
+
+```js
+// WRONG
+var data = {
+    content: new ArrayBuffer(...)
+};
+zip.file("my.data", data); // won't work, data is an object
+
+// CORRECT
+var data = new ArrayBuffer(...);
+zip.file("my.data", data); // will work, JSZip accepts ArrayBuffer
+```

lib/utils.js

@@ -454,7 +454,8 @@ exports.prepareContent = function(name, inputData, isBinary, isOptimizedBinarySt
 
         if (!dataType) {
             return external.Promise.reject(
-                new Error("The data of '" + name + "' is in an unsupported format !")
+                new Error("Can't read the data of '" + name + "'. Is it " +
+                          "in a supported JavaScript type (String, Blob, ArrayBuffer, etc) ?")
             );
         }
         // special case : it's way easier to work with Uint8Array than with ArrayBuffer

test/asserts/file.js

@@ -345,7 +345,7 @@ QUnit.module("file", function () {
             ok(false, "An unsupported object was added, but no exception thrown");
         }, function (e) {
             start();
-            ok(e.message.match("unsupported format"), "the error message is useful");
+            ok(e.message.match("Is it in a supported JavaScript type"), "the error message is useful");
         });
     });