Mention exporting memory utilities more prominently in loader readme, fixes #318

lib/loader/README.md

@@ -61,21 +61,16 @@ Instances are automatically populated with useful utility:
   A 64-bit float view on the memory.
 
 * **newString**(str: `string`): `number`<br />
-  Allocates a new string in the module's memory and returns its pointer. Requires `memory.allocate` to be exported from your module's entry file, i.e.:
+  Allocates a new string in the module's memory and returns its pointer.<sup>2</sup>
-
-  ```js
-  import "allocator/tlsf";
-  export { memory };
-  ```
 
 * **getString**(ptr: `number`): `string`<br />
   Gets a string from the module's memory by its pointer.
 
 * **newArray**(view: `TypedArray`, length?: `number`, unsafe?: `boolean`): `number`<br />
-  Copies a typed array into the module's memory and returns its pointer.
+  Copies a typed array into the module's memory and returns its pointer.<sup>2</sup>
 
 * **newArray**(ctor: `TypedArrayConstructor`, length: `number`, unsafe?: `boolean`): `number`<br />
-  Creates a typed array in the module's memory and returns its pointer.
+  Creates a typed array in the module's memory and returns its pointer.<sup>2</sup>
 
 * **getArray**(ctor: `TypedArrayConstructor`, ptr: `number`): `TypedArray`<br />
   Gets a view on a typed array in the module's memory by its pointer.
@@ -90,7 +85,8 @@ Instances are automatically populated with useful utility:
   Creates a new function in the module's table and returns its pointer. Note that only actual
   WebAssembly functions, i.e. as exported by the module, are supported.
 
-<sup>1</sup> This feature has not yet landed in any VM as of this writing.
+<sup>1</sup> This feature has not yet landed in any VM as of this writing.<br />
+<sup>2</sup> Requires that memory utilities have been exported through `export { memory }` within the entry file.
 
 Examples
 --------
@@ -137,19 +133,24 @@ myModule.F64[ptrToFloat64 >>> 3] = newValue;
 
 **Note:** Make sure to reference the views as shown above as these will automatically be updated when the module's memory grows.
 
-### Allocating/obtaining strings to/from memory
+### Working with strings and arrays
+
+Strings and arrays cannot yet flow in and out of WebAssembly naturally, hence it is necessary to create them in the module's memory using the `newString` and `newArray` helpers. Afterwards, instead of passing the string or array directly, the resulting reference (pointer) is provided instead:
 
 ```js
-// Allocating a string, i.e. to be passed to an export expecting one
 var str = "Hello world!";
 var ptr = module.newString(str);
 
-// Disposing a string that is no longer needed (requires memory.free to be exported)
+// ... do something with ptr, i.e. call a WebAssembly export ...
-module.memory.free(ptr);
+```
 
-// Obtaining a string, i.e. as returned by an export
+Similarly, when a string or array is returned from a WebAssembly function, a reference (pointer) is received on the JS side and the `getString` and `getArray` helpers can be used to obtain their values:
+
+```js
 var ptrToString = ...;
 var str = module.getString(ptrToString);
+
+// ... do something with str ...
 ```
 
 ### Usage with TypeScript definitions produced by the compiler