docs for Flash #1349

documentation/files/files.md

@@ -1,6 +1,6 @@
 # Files
-Copyright 2017-2023 Moddable Tech, Inc.<BR>
-Revised: September 7, 2023
+Copyright 2017-2024 Moddable Tech, Inc.<BR>
+Revised: August 1, 2024
 
 ## Table of Contents
 
@@ -705,6 +705,46 @@ for (let key of wifiKeys)
 <a id="flash"></a>
 ## class Flash
 
-This class is not yet documented.
+- **Source code:** [file](../../modules/files/flash)
 
-N.B. The `readString()` API is considered experimental. It assumes that the input is a valid UTF-8 string.
+The `Flash` class provides access to flash memory partitions.
+
+### `constructor(name)`
+The Flash constructor creates an instance bound to the partition indicated by the `name` argument. The names of available partitions, if any, are host-dependent.
+
+***
+### `close()`
+
+Releases all resources held by the Flash instance. Calls to any methods of the instance made after calling `close()` throw.
+
+***
+### `erase(block)`
+
+Erases one block of the flash partition. The `block` argument is the index of the block within the partition, starting with block 0. To convert from block number to index, multiply by the instance's `blockSize`.
+
+***
+### `read(offset, byteLength)`
+
+Reads `byteLength` bytes starting at byte `offset` in the partition into an `ArrayBuffer`.
+
+***
+### `write(offset, byteLength, buffer)`
+
+Writes the first `byteLength` bytes from `buffer` starting at byte `offset` in the partition. The `buffer` argument may be any byte buffer.
+
+***
+### `map()`
+Returns a read-only host buffer that may be wrapped in a view to read directly from the flash partition. If `map()` is not supported by the host, the function throws an exception.
+
+***
+
+### `byteLength`
+The read-only `byteLength` property provides the size of the flash partition.
+
+***
+### `blockSize`
+The read-only `blockSize` property provides the size of a block (aka sector) in the flash partition. Using this value is recommended instead of hard-coding the common flash block size of `4096`.
+
+***
+
+**Note**. The `readString()` API is experimental and should not be used in production. It is potentially unsafe because it assumes that the input is a valid UTF-8 string.

modules/files/flash/flash.js

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2016-2023  Moddable Tech, Inc.
+ * Copyright (c) 2016-2024  Moddable Tech, Inc.
  *
  *   This file is part of the Moddable SDK Runtime.
  * 
@@ -23,7 +23,7 @@ class Flash @ "xs_flash_destructor" {
 
 	// sector and offsets are relative to area opened in constructor
 	erase(sector) @ "xs_flash_erase";
-	read(offset, byteLength, buffer) @ "xs_flash_read";
+	read(offset, byteLength) @ "xs_flash_read";
 	readString(offset, byteLength) @ "xs_flash_readString";
 	write(offset, byteLength, buffer) @ "xs_flash_write";
 	map() @ "xs_flash_map"