patch: run docs on jacdac.ts, including servers

src/jdom/device.ts

@@ -49,6 +49,10 @@ import LEDController from "./ledcontroller"
 import JDEventSource from "./eventsource"
 import { ServiceFilter } from "./filters/servicefilter"
 
+/**
+ * Pipe information
+ * @category Runtime
+ */
 export interface PipeInfo {
     pipeType?: string
     // eslint-disable-next-line @typescript-eslint/no-explicit-any

src/jdom/eventsource.ts

@@ -2,6 +2,9 @@ import { NEW_LISTENER, REMOVE_LISTENER, ERROR, CHANGE } from "./constants"
 import { Observable, Observer } from "./observable"
 import Flags from "./flags"
 
+/**
+ * @category JDOM
+ */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type EventHandler = (...args: any[]) => void
 
@@ -36,8 +39,16 @@ export interface IEventSource {
     ): () => void
 }
 
-export function dependencyId(nodes: IEventSource[]) {
-    return nodes?.map(node => node?.nodeId || "?").join(",") || ""
+/**
+ * Given a node or set of nodes, generate a stable string that can be used to track dependencies in frameworks like React.
+ * @param nodes 
+ * @returns 
+ * @category JDOM
+ */
+export function dependencyId(nodes: IEventSource | IEventSource[]) {
+    if (Array.isArray(nodes))
+        return nodes?.map(node => node?.nodeId || "?").join(",") || ""
+    else return nodes?.nodeId || ""
 }
 
 let nextNodeId = 0

src/jdom/observable.ts

@@ -1,9 +1,15 @@
+/**
+ * @internal
+ */
 export interface Observer<T> {
     next?: (value: T) => void
     error?: (error: Error) => void
     complete?: () => void
 }
 
+/**
+ * @internal
+ */
 export interface Observable<T> {
     subscribe(observer: Observer<T>): {
         unsubscribe: () => void

src/jdom/packetfilter.ts

@@ -8,8 +8,16 @@ import JDBus from "./bus"
 import Packet from "./packet"
 import { isInstanceOf, serviceSpecificationFromName } from "./spec"
 
+/**
+ * @category Trace
+ * @internal
+ */
 export type CompiledPacketFilter = (pkt: Packet) => boolean
 
+/**
+ * @category Trace
+ * @internal
+ */
 export interface PacketFilterProps {
     announce?: boolean
     repeatedAnnounce?: boolean
@@ -35,6 +43,9 @@ export interface PacketFilterProps {
     collapseGets?: boolean
 }
 
+/**
+ * @internal
+ */
 export interface PacketFilter {
     source: string
     props: PacketFilterProps

src/jdom/rolemanager.ts

@@ -13,6 +13,10 @@ import JDService from "./service"
 import { serviceSpecificationFromClassIdentifier } from "./spec"
 import { JDClient } from "./client"
 
+/**
+ * A binding from a name to a service
+ * @category Roles
+ */
 export interface RoleBinding {
     role: string
     serviceClass: number

src/jdom/utils.ts

@@ -644,3 +644,18 @@ export function range(end: number): number[] {
         .fill(0)
         .map((_, i) => i)
 }
+
+export function toggleBit(data: Uint8Array, bitindex: number) {
+    // find bit to flip
+    let byte = data[bitindex >> 3]
+    const bit = bitindex % 8
+    const on = 1 === ((byte >> bit) & 1)
+    // flip bit
+    if (on) {
+        byte &= ~(1 << bit)
+    } else {
+        byte |= 1 << bit
+    }
+    // save
+    data[bitindex >> 3] = byte
+}

src/servers/analogsensorserver.ts

@@ -1,8 +1,13 @@
 import { SystemReg } from "../jdom/constants"
 import JDRegisterServer from "../jdom/registerserver"
-import { LevelDetector } from "./leveldetector"
+import LevelDetector from "./leveldetector"
 import SensorServer, { SensorServiceOptions } from "./sensorserver"
 
+/**
+ * Creation options for AnalogSensorServer
+ * @category Servers
+ * @internal
+ */
 export interface AnalogSensorServerOptions
     extends SensorServiceOptions<[number]> {
     minReading?: number
@@ -12,6 +17,10 @@ export interface AnalogSensorServerOptions
     readingResolution?: number
 }
 
+/**
+ * Base class for analog sensor servers
+ * @category Servers
+ */
 export default class AnalogSensorServer extends SensorServer<[number]> {
     readonly inactiveThreshold: JDRegisterServer<[number]>
     readonly activeThreshold: JDRegisterServer<[number]>

src/servers/azureiothubserver.ts

@@ -10,17 +10,31 @@ import RegisterServer from "../jdom/registerserver"
 import Packet from "../jdom/packet"
 import { jdpack } from "../jdom/pack"
 
+/**
+ * Server creation options for the Azure IoT hub message
+ * @category Servers
+ * @internal
+ */
 export interface AzureIoTHubServerOptions extends ServerOptions {
     hubName?: string
     deviceId?: string
 }
 
-export class AzureIoTHubMessage {
+/**
+ * A Azure IoT hub message
+ * @category Servers
+ * @internal
+ */
+export interface AzureIoTHubMessage {
     counter: number
     timestamp: number
     body: string
 }
 
+/**
+ * A server implementation of the bit:radio service
+ * @category Servers
+ */
 export default class AzureIoTHubServer extends JDServiceServer {
     readonly hubName: RegisterServer<[string]>
     readonly deviceId: RegisterServer<[string]>

src/servers/bitradioserver.ts

@@ -198,6 +198,10 @@ class RadioPacket {
     }
 }
 
+/**
+ * A server implementation of the bit:radio service
+ * @category Servers
+ */
 export default class BitRadioServer extends JDServiceServer {
     readonly enabled: JDRegisterServer<[number]>
     readonly group: JDRegisterServer<[number]>

src/servers/buttonserver.ts

@@ -9,6 +9,10 @@ import SensorServer from "./sensorserver"
 import RegisterServer from "../jdom/registerserver"
 import { jdpack } from "../jdom/pack"
 
+/**
+ * Server implementation for the button service
+ * @category Servers
+ */
 export default class ButtonServer extends SensorServer<[number]> {
     public static readonly HOLD_TIME = 500
     public static readonly INACTIVE_VALUE = 0

src/servers/buzzerserver.ts

@@ -4,18 +4,33 @@ import Packet from "../jdom/packet"
 import JDRegisterServer from "../jdom/registerserver"
 import JDServiceServer, { ServerOptions } from "../jdom/serviceserver"
 
+/**
+ * @internal
+ */
 export interface BuzzerTone {
     frequency: number
     duration: number
     volume: number
 }
 
+/**
+ * Encodes a buzzer tone information into a data payload
+ * @param frequency sound frequency in Hz
+ * @param ms sound duration in milliseconds
+ * @param volume volume from [0..1]
+ * @returns data payload
+ * @category Data Packing
+ */
 export function tonePayload(frequency: number, ms: number, volume: number) {
     const period = Math.round(1000000 / frequency)
     const duty = (period * volume) >> 11
     return jdpack("u16 u16 u16", [period, duty, ms])
 }
 
+/**
+ * Server implementation for the buzzer service
+ * @category Servers
+ */
 export default class BuzzerServer extends JDServiceServer {
     readonly volume: JDRegisterServer<[number]>
 

src/servers/hidkeyboardserver.ts

@@ -39,7 +39,9 @@ export default class HIDKeyboardServer extends JDServiceServer {
         }
     }
 }
-
+/**
+ * @internal
+ */
 export const selectors: SMap<number> = {
     a: 0x04,
     b: 0x05,
@@ -191,6 +193,9 @@ export const selectors: SMap<number> = {
 
     numpadcomma: 0x85,
 }
+/**
+ * @internal
+ */
 export const reverseSelectors: { [index: number]: string } = Object.keys(
     selectors
 ).reduce((r, key) => {
@@ -198,6 +203,9 @@ export const reverseSelectors: { [index: number]: string } = Object.keys(
     return r
 }, {} as { [index: number]: string })
 
+/**
+ * @internal
+ */
 export const modifierCodes = {
     controlleft: HidKeyboardModifiers.LeftControl,
     altleft: HidKeyboardModifiers.LeftAlt,
@@ -210,6 +218,9 @@ export const modifierCodes = {
     metaright: HidKeyboardModifiers.RightGUI,
 }
 
+/**
+ * @internal
+ */
 export function renderKeyboardKey(
     selector: number,
     modifiers: HidKeyboardModifiers,

src/servers/hidmouseserver.ts

@@ -8,6 +8,9 @@ import {
 import Packet from "../jdom/packet"
 import JDServiceServer, { ServerOptions } from "../jdom/serviceserver"
 
+/**
+ * @internal
+ */
 export function renderHidMouseButtons(buttons: HidMouseButton) {
     const btns = [
         buttons & HidMouseButton.Left ? "left" : "",

src/servers/joystickserver.ts

@@ -7,12 +7,18 @@ import {
 import JDRegisterServer from "../jdom/registerserver"
 import SensorServer from "./sensorserver"
 
+/**
+ * @internal
+ */
 export const JOYSTICK_DPAD_BUTTONS =
     JoystickButtons.Left |
     JoystickButtons.Right |
     JoystickButtons.Up |
     JoystickButtons.Down
 
+/**
+ * @internal
+ */
 export const JOYSTICK_ARCADE_BUTTONS =
     JOYSTICK_DPAD_BUTTONS |
     JoystickButtons.A |
@@ -21,11 +27,20 @@ export const JOYSTICK_ARCADE_BUTTONS =
     JoystickButtons.Select |
     JoystickButtons.Exit
 
+/**
+ * @internal
+ */
 export const JOYSTICK_DPAD_A_BUTTONS = JOYSTICK_DPAD_BUTTONS | JoystickButtons.A
 
+/**
+ * @internal
+ */
 export const JOYSTICK_DPAD_AB_BUTTONS =
     JOYSTICK_DPAD_A_BUTTONS | JoystickButtons.B
 
+/**
+ * @internal
+ */
 export const JOYSTICK_GAMEPAD_EXTRA_BUTTONS =
     JoystickButtons.B |
     JoystickButtons.Select |

src/servers/ledmatrixserver.ts

@@ -7,21 +7,6 @@ import {
 import JDRegisterServer from "../jdom/registerserver"
 import JDServiceServer from "../jdom/serviceserver"
 
-export function toggle(data: Uint8Array, bitindex: number) {
-    // find bit to flip
-    let byte = data[bitindex >> 3]
-    const bit = bitindex % 8
-    const on = 1 === ((byte >> bit) & 1)
-    // flip bit
-    if (on) {
-        byte &= ~(1 << bit)
-    } else {
-        byte |= 1 << bit
-    }
-    // save
-    data[bitindex >> 3] = byte
-}
-
 export default class LEDMatrixServer extends JDServiceServer {
     readonly leds: JDRegisterServer<[Uint8Array]>
     readonly rows: JDRegisterServer<[number]>

src/servers/leveldetector.ts

@@ -2,7 +2,7 @@ import { JDClient } from "../jdom/client"
 import { CHANGE, SystemEvent, SystemReadingThreshold } from "../jdom/constants"
 import AnalogSensorServer from "./analogsensorserver"
 
-export class LevelDetector extends JDClient {
+export default class LevelDetector extends JDClient {
     private _state: number
 
     constructor(readonly service: AnalogSensorServer) {

src/servers/realtimeclockserver.ts

@@ -10,6 +10,9 @@ import JDRegisterServer from "../jdom/registerserver"
 import JDBus from "../jdom/bus"
 import Packet from "../jdom/packet"
 
+/**
+ * @internal
+ */
 export type RealTimeClockReadingType = [
     number,
     number,
@@ -20,6 +23,9 @@ export type RealTimeClockReadingType = [
     number
 ]
 
+/**
+ * @internal
+ */
 export function dateToClock(n: Date): RealTimeClockReadingType {
     const year = n.getFullYear()
     const month = n.getMonth() + 1

src/servers/sensorserver.ts

@@ -4,6 +4,11 @@ import { PackedValues } from "../jdom/pack"
 import JDRegisterServer from "../jdom/registerserver"
 import JDServiceServer, { ServerOptions } from "../jdom/serviceserver"
 
+/**
+ * Creation options for sensor servers
+ * @category Servers
+ * @internal
+ */
 export interface SensorServiceOptions<TReading extends PackedValues>
     extends ServerOptions {
     readingValues?: TReading

src/servers/servers.ts

@@ -163,6 +163,9 @@ const sonarOptions: AnalogSensorServerOptions = {
 }
 
 const SG90_STALL_TORQUE = 1.8
+/**
+ * @internal
+ */
 export const SG90_RESPONSE_SPEED = 0.12 // deg/60deg
 
 const microServoOptions = {
@@ -260,11 +263,30 @@ const soundSpectrum: SensorServiceOptions<[Uint8Array]> = {
     ],
 }
 
+/**
+ * A factory for instantiation a simulated service server
+ * @category Servers
+ */
 export interface ServiceProviderDefinition {
+    /**
+     * Name of the simulated device
+     */
     name: string
+    /**
+     * List of service classes hosted by the provider
+     */
     serviceClasses: number[]
+    /**
+     * Factory handler to instantiate simulated servers
+     */
     services: () => JDServiceServer[]
+    /**
+     * Indicates if the simulated device should support resetId
+     */
     resetIn?: boolean
+    /**
+     * Custom factory to wrap the services into a servie provider
+     */
     factory?: (services: JDServiceServer[]) => JDServiceProvider
 }
 
@@ -1339,10 +1361,18 @@ const _providerDefinitions: ServiceProviderDefinition[] = [
     },
 ]
 
+/**
+ * Gets the list of simulated service providers
+ * @category Servers
+ */
 export default function serviceProviderDefinitions() {
     return _providerDefinitions.slice(0)
 }
 
+/**
+ * Instantiates a new service provider instance and adds it to the bus
+ * @category Servers
+ */
 export function addServiceProvider(
     bus: JDBus,
     definition: ServiceProviderDefinition
@@ -1358,6 +1388,10 @@ export function addServiceProvider(
     return d
 }
 
+/**
+ * Finds the first service provider that supports the given service class
+ * @category Servers
+ */
 export function serviceProviderDefinitionFromServiceClass(
     serviceClass: number
 ) {
@@ -1368,6 +1402,10 @@ export function serviceProviderDefinitionFromServiceClass(
     )
 }
 
+/**
+ * Starts a service provider that hosts the given service class.
+ * @category Servers
+ */
 export function startServiceProviderFromServiceClass(
     bus: JDBus,
     serviceClass: number

src/servers/soundplayerserver.ts

@@ -9,6 +9,9 @@ import { OutPipe } from "../jdom/pipes"
 import JDRegisterServer from "../jdom/registerserver"
 import JDServiceServer from "../jdom/serviceserver"
 
+/**
+ * @internal
+ */
 export type SoundPlayerSound = [number, string]
 
 export default class SoundPlayerServer extends JDServiceServer {

typedoc.json

@@ -1,5 +1,5 @@
 {
-    "entryPoints": ["src/jdom/jacdac-jdom.ts"],
+    "entryPoints": ["src/jacdac.ts"],
     "out": "docs",
     "exclude": [
         "src/worker/*.ts",