Generate docs using TypeDocs, document usage in README.md

Author: microbit-grace

.gitignore

@@ -11,6 +11,7 @@ node_modules
 dist
 dist-ssr
 *.local
+docs
 
 # Editor directories and files
 .vscode/*

README.md

@@ -1,17 +1,90 @@
-# JavaScript library for micro:bit connections in browsers via USB and Bluetooth
+# micro:bit connection library
+
+This is a JavaScript library for micro:bit connections in browsers via USB and Bluetooth.
 
 This project is a work in progress. We are extracting WebUSB and Web Bluetooth code from the [micro:bit Python Editor](https://github.com/microbit-foundation/python-editor-v3/) and other projects.
 
 It is intended to be used by other Micro:bit Educational Foundation projects that need to connect to a BBC micro:bit.
 
 The API is not stable and it's not yet recommended that third parties use this project unless they are happy to update usage as the API evolves.
 
+[Demo site](https://microbit-connection.pages.dev/) for this library.
+
 [Alpha releases are now on NPM](https://www.npmjs.com/package/@microbit/microbit-connection).
 
 [This Python Editor PR](https://github.com/microbit-foundation/python-editor-v3/pull/1190) tracks updating the micro:bit Python Editor to use this library.
 
 [micro:bit CreateAI](https://github.com/microbit-foundation/ml-trainer/) is already using this library for WebUSB and Web Bluetooth.
 
+## Usage
+
+### Flash a micro:bit
+
+Instantiate a WebUSB connection using {@link MicrobitWebUSBConnection} class and use it to connect to a micro:bit.
+
+```ts
+import { MicrobitWebUSBConnection } from "@microbit/microbit-connection";
+
+const usb = new MicrobitWebUSBConnection();
+const connectionStatus = await usb.connect();
+
+console.log("Connection status: ", connectionStatus);
+```
+
+{@link ConnectionStatus | Connection status} is `"CONNECTED"` if connection succeeds.
+
+Create a Universal Hex that supports both V1 and V2 micro:bits using {@link createUniversalHexFlashDataSource} and flash the micro:bit.
+
+```ts
+import { createUniversalHexFlashDataSource } from "@microbit/microbit-connection";
+
+const universalHex = createUniversalHexFlashDataSource(text);
+await usb.flash(universalHex, {
+  partial: true,
+  progress: (percentage: number | undefined) => {
+    console.log(percentage);
+  },
+});
+```
+
+Alternatively, you can create and flash a hex that supports a specific micro:bit version (V1 or V2) using the [@microbit/microbit-fs library](https://microbit-foundation.github.io/microbit-fs/). Below is an example of creating a hex for V1 and using it to flash the micro:bit.
+
+```ts
+import { MicropythonFsHex } from "@microbit/microbit-fs";
+import { BoardId } from "@microbit/microbit-connection";
+
+const boardId = BoardId.forVersion("V1").id;
+const micropythonFs = new MicropythonFsHex([{ hex: intelHexString, boardId }]);
+const hex = micropythonFs.getIntelHex(boardId);
+await usb.flash(async () => hex, {
+  partial: true,
+  progress: (percentage: number | undefined) => {
+    console.log(percentage);
+  },
+});
+```
+
+For more examples of using other methods in the {@link MicrobitWebUSBConnection} class, see our [demo code](https://github.com/microbit-foundation/microbit-connection/blob/main/src/demo.ts) for our [demo site](https://microbit-connection.pages.dev/).
+
+### Connect via Bluetooth
+
+By default, the micro:bit's Bluetooth service is not enabled. Visit our [Bluetooth tech site page](https://tech.microbit.org/bluetooth/) to download a hex file that would enable the bluetooth service.
+
+Instantiate a Bluetooth connection using {@link MicrobitWebBluetoothConnection} class and use it to connect to a micro:bit.
+
+```ts
+import { MicrobitWebBluetoothConnection } from "@microbit/microbit-connection";
+
+const bluetooth = new MicrobitWebBluetoothConnection();
+const connectionStatus = await bluetooth.connect();
+
+console.log("Connection status: ", connectionStatus);
+```
+
+{@link ConnectionStatus | Connection status} is `"CONNECTED"` if connection succeeds.
+
+For more examples of using other methods in the {@link MicrobitWebBluetoothConnection} class, see our [demo code](https://github.com/microbit-foundation/microbit-connection/blob/main/src/demo.ts) for our [demo site](https://microbit-connection.pages.dev/).
+
 ## License
 
 This software is under the MIT open source license.

package-lock.json

@@ -25,12 +25,14 @@
     "build": "npm run build:lib && npm run build:demo",
     "ci": "npm run build:lib && npm run test && npx prettier --check lib src",
     "test": "vitest",
-    "preview": "vite preview"
+    "preview": "vite preview",
+    "docs": "typedoc"
   },
   "devDependencies": {
     "@types/node": "^20.14.10",
     "jsdom": "^24.1.0",
     "prettier": "3.3.2",
+    "typedoc": "^0.27.6",
     "typescript": "^5.2.2",
     "vite": "^5.3.1",
     "vitest": "^2.0.0"