Documentation request for Flash

[stc1988]

Flash class is not yet documented..
Or, if documentation is difficult, it would be helpful to have a brief explanation of scenarios where this class is used or an example application.

[phoddie]

It is true that the Flash class is not described in files.md. There is quite a bit of information available, however.

• The Flash class is not documented in this repository, but it is covered in depth in the Files chapter of our book.
• There are three examples of using Flash in our book. Its repository of examples contains those.
• There are unit tests in this repository.
• The contributed Giphy app uses Flash to stored the downloaded animated GIF.

I suppose we could generate some basic documentation based on these sources.

[stc1988]

First, I'll read it since I already have the book.

[phoddie]

@stc1988 – There is no great urgency here, but I wanted to ask if you had any further thoughts on how we should best proceed here.

[stc1988]

Ideally, it would include a detailed definition of the class and representative use cases, as with other classes. However, documenting the use cases for the flash class seems voluminous. Additionally, as mentioned in the book, accessing Flash directly is dangerous, so it is desirable that the documentation is not incomplete.

Therefore, as the first step, I think it would be a good idea to provide a simple explanation of the class and introduce links to useful applications.

[phoddie]

I've written basic documentation for the Flash class. The text is below. It will be in the next repository update.

---

class Flash

• Source code: file

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.

[stc1988]

It looks good. Thank you!

[stc1988]

I confirmed that it was added.　Thank you.