Add help documentation and docstrings (#29)

---------

Co-authored-by: Matt Hillsdon <[email protected]>

_locales/machine-learning-jsdoc-strings.json

@@ -1 +1,15 @@
-{}
+{
+  "ml.getCertainty": "Get the certainty of an ML event in percent (0 to 100).",
+  "ml.getCertainty|param|event": "one of the actions the machine learning model was trained on",
+  "ml.isDetected": "Tests if an ML event is currently detected.",
+  "ml.isDetected|param|event": "one of the actions the machine learning model was trained on",
+  "ml.onStart": "Do something when an ML event is detected.",
+  "ml.onStart|param|body": "code to execute",
+  "ml.onStart|param|event": "one of the actions the machine learning model was trained on",
+  "ml.onStop": "Do something when an ML event is no longer detected.",
+  "ml.onStopDetailed": "Do something when an ML event is no longer detected.",
+  "ml.onStopDetailed|param|body": "code to execute",
+  "ml.onStopDetailed|param|event": "one of the actions the machine learning model was trained on",
+  "ml.onStop|param|body": "code to execute",
+  "ml.onStop|param|event": "one of the actions the machine learning model was trained on"
+}

_locales/machine-learning-strings.json

@@ -5,6 +5,7 @@
   "ml.onStart|block": "on ML $event start",
   "ml.onStopDetailed|block": "on ML $event stop $duration (ms)",
   "ml.onStop|block": "on ML $event stop",
+  "ml|block": "Machine Learning",
   "{id:category}Ml": "Ml",
   "{id:category}MlEvent": "MlEvent",
   "{id:group}micro:bit (V2)": "micro:bit (V2)"

docs/ml_get_event_certainty.md

@@ -0,0 +1,32 @@
+# on ML start
+
+Gets the latest certainty value for an ML action.
+
+```sig
+ml.getCertainty(ml.event.Unknown)
+```
+
+The ML model runs several times a second and calculates a certainty value for each action. The estimated action is the action with the highest certainty. An action cannot be the estimated action when its certainty is below the recognition point. Some programs may need to use the certainty values directly, for example to display or log them. Most programs can use the estimated action instead of certainty values.
+
+## Parameters
+
+- **event**: one of the actions the machine learning model was trained on.
+
+## Returns
+
+- a percentage as a [number](/types/number) from 0 to 100, representing the ML model’s certainty that this is the action being performed. The certainty for `unknown` is always 0.
+
+## Example
+
+This example displays the ML model's certainty, in percent, that the current action is `clapping` every second.
+
+```blocks
+loops.everyInterval(1000, function () {
+    basic.showNumber(ml.getCertainty(ml.event.Clapping))
+})
+```
+
+```package
+machine-learning-help-stubs=github:microbit-foundation/pxt-microbit-ml-help-stubs#v0.0.1
+machine-learning=github:microbit-foundation/pxt-microbit-ml#v1.0.2
+```

docs/ml_is_event_detected.md

@@ -0,0 +1,36 @@
+# is ML detected
+
+Checks if an ML action is the estimated action.
+
+```sig
+ml.isDetected(ml.event.Unknown)
+```
+
+The ML model updates its estimated action several times a second. This function returns `true` if the chosen action is currently estimated. Use the boolean value to make logical decisions in your program.
+
+Some programs will be easier to write using the “on ML start” and “on ML stop” event handlers instead.
+
+## Parameters
+
+- **event**: one of the actions the machine learning model was trained on. The special value `unknown` represents the case where no action has a certainty above the recognition point.
+
+## Returns
+
+- a [boolean](/types/boolean) value that is `true` if the ML action is the estimated action, `false` if the ML action is not the estimated action.
+
+## Example
+
+This example will show a tick icon on the LED display if the estimated action is `clapping` at the time the conditional statement is checked.
+
+```blocks
+basic.forever(function () {
+    if (ml.isDetected(ml.event.Clapping)) {
+        basic.showIcon(IconNames.Yes)
+    }
+})
+```
+
+```package
+machine-learning-help-stubs=github:microbit-foundation/pxt-microbit-ml-help-stubs#v0.0.1
+machine-learning=github:microbit-foundation/pxt-microbit-ml#v1.0.2
+```

docs/ml_on_event_start.md

@@ -0,0 +1,29 @@
+# on ML start
+
+Start an [event handler](/reference/event-handler) (part of the program that will run when something happens). This handler works when the ML model’s estimated action changes to the action you select.
+
+```sig
+ml.onStart(ml.event.Unknown, function () {
+})
+```
+
+The ML model updates its estimated action several times a second, but this event handler only runs when the estimated action changes.
+
+## Parameters
+
+- **event**: one of the actions the machine learning model was trained on. The special value `unknown` represents the case where no action has a certainty above the recognition point.
+
+## Example
+
+This example plays a musical melody in the background when the action `clapping` has a certainty above the recognition point.
+
+```blocks
+ml.onStart(ml.event.Clapping, function () {
+    music._playDefaultBackground(music.builtInPlayableMelody(Melodies.Dadadadum), music.PlaybackMode.InBackground)
+})
+```
+
+```package
+machine-learning-help-stubs=github:microbit-foundation/pxt-microbit-ml-help-stubs#v0.0.1
+machine-learning=github:microbit-foundation/pxt-microbit-ml#v1.0.2
+```

docs/ml_on_event_stop.md

@@ -0,0 +1,31 @@
+# on ML stop
+
+Start an [event handler](/reference/event-handler) (part of the program that will run when something happens). This handler works when the ML model’s estimated action changes from the action you select.
+
+```sig
+ml.onStop(ml.event.Unknown, function () {
+})
+```
+
+When an action changes, the stop event handler for the previous action will run, followed by the start event handler for the next action.
+
+For example, if your start event handler for an action starts music playing in the background, you could use a stop event handler to stop it.
+
+## Parameters
+
+- **event**: one of the actions the machine learning model was trained on. The special value `unknown` represents the case where no action has a certainty above the recognition point.
+
+## Example
+
+This example stops playing a musical melody when the estimated action changes from `clapping` to any other action.
+
+```blocks
+ml.onStop(ml.event.Clapping, function () {
+    music.stopMelody(MelodyStopOptions.All)
+})
+```
+
+```package
+machine-learning-help-stubs=github:microbit-foundation/pxt-microbit-ml-help-stubs#v0.0.1
+machine-learning=github:microbit-foundation/pxt-microbit-ml#v1.0.2
+```

docs/ml_on_event_stop_detailed.md

@@ -0,0 +1,33 @@
+# on ML stop
+
+Start an [event handler](/reference/event-handler) (part of the program that will run when something happens). This handler works when the ML model’s estimated action changes from the action you select.
+
+```sig
+ml.onStopDetailed(ml.event.Unknown, function (duration) {
+})
+```
+
+When an action changes, the stop event handler for the previous action will run, followed by the start event handler for the next action.
+
+For example, if your start event handler for an action starts music playing in the background, you could use a stop event handler to stop it.
+
+The event handler is passed a `duration` parameter. The duration is the [number](/types/number) of milliseconds since this action became the estimated action. You can use the duration parameter in your code, for example displaying it or using a variable to keep a running total.
+
+## Parameters
+
+- **event**: one of the actions the machine learning model was trained on. The special value `unknown` represents the case where no action has a certainty above the recognition point.
+
+## Example
+
+This example shows on the LED display, in seconds, how long the estimated action was `clapping`, when the estimated action changes from `clapping` to any other action.
+
+```blocks
+ml.onStopDetailed(ml.event.Clapping, function (duration) {
+    basic.showNumber(duration / 1000)
+})
+```
+
+```package
+machine-learning-help-stubs=github:microbit-foundation/pxt-microbit-ml-help-stubs#v0.0.1
+machine-learning=github:microbit-foundation/pxt-microbit-ml#v1.0.2
+```

pxt.json

@@ -10,7 +10,12 @@
         "README.md",
         "enums.d.ts",
         "pxtextension.ts",
-        "pxtextension.cpp"
+        "pxtextension.cpp",
+        "docs/ml_is_event_detected.md",
+        "docs/ml_get_event_certainty.md",
+        "docs/ml_on_event_start.md",
+        "docs/ml_on_event_stop.md",
+        "docs/ml_on_event_stop_detailed.md"
     ],
     "testFiles": [
         "autogenerated.ts",

pxtextension.ts

@@ -51,12 +51,17 @@ namespace ml {
     }
   }
 
+  /**
+   * Do something when an ML event is detected.
+   * @param event one of the actions the machine learning model was trained on
+   * @param body code to execute
+   */
   //% blockId=ml_on_event_start
   //% block="on ML $event start"
   //% weight=50
   //% parts="v2"
   //% group="micro:bit (V2)"
-  //% help=none
+  //% help=github:machine-learning/docs/ml_on_event_start
   export function onStart(event: MlEvent, body: () => void): void {
     event.onStartHandler = body;
     const wrappedBody = () => {
@@ -77,26 +82,36 @@ namespace ml {
     );
   }
 
+  /**
+   * Do something when an ML event is no longer detected.
+   * @param event one of the actions the machine learning model was trained on
+   * @param body code to execute
+   */
   //% blockId=ml_on_event_stop
   //% block="on ML $event stop"
   //% weight=40
   //% parts="v2"
   //% group="micro:bit (V2)"
-  //% help=none
+  //% help=github:machine-learning/docs/ml_on_event_stop
   export function onStop(event: MlEvent, body: () => void): void {
     if (!isRunning()) {
       startRunning();
     }
     event.onStopHandler = body;
   }
 
+  /**
+   * Do something when an ML event is no longer detected.
+   * @param event one of the actions the machine learning model was trained on
+   * @param body code to execute
+   */
   //% blockId=ml_on_event_stop_detailed
   //% block="on ML $event stop $duration (ms)"
   //% weight=30
   //% draggableParameters="reporter"
   //% parts="v2"
   //% group="micro:bit (V2)"
-  //% help=none
+  //% help=github:machine-learning/docs/ml_on_event_stop_detailed
   export function onStopDetailed(
     event: MlEvent,
     body: (duration: number) => void
@@ -107,12 +122,16 @@ namespace ml {
     event.onStopDetailedHandler = body;
   }
 
+  /**
+   * Tests if an ML event is currently detected.
+   * @param event one of the actions the machine learning model was trained on
+   */
   //% blockId=ml_is_event_detected
   //% block="is ML $event detected"
   //% weight=20
   //% parts="v2"
   //% group="micro:bit (V2)"
-  //% help=none
+  //% help=github:machine-learning/docs/ml_is_event_detected
   export function isDetected(event: MlEvent): boolean {
     if (!isRunning()) {
       startRunning();
@@ -121,11 +140,15 @@ namespace ml {
     return event.eventValue == currentEventId();
   }
 
+  /**
+   * Get the certainty of an ML event in percent (0 to 100).
+   * @param event one of the actions the machine learning model was trained on
+   */
   //% blockId=ml_on_event_certainty
   //% block="certainty (\\%) ML $event"
   //% weight=10
   //% parts="v2"
-  //% help=none
+  //% help=github:machine-learning/docs/ml_get_event_certainty
   export function getCertainty(event: MlEvent): number {
     const eventValue = event.eventValue;
     if (eventValue <= 1) {