First pass help docs and docstring test

Author: microbit-robert

docs/ml_get_event_certainty.md

@@ -0,0 +1,31 @@
+# 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 is not considered when its certainty is below the recognition point). Some programs may want to access 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 that the current action is `unknown` every second.
+
+```blocks
+loops.everyInterval(1000, function () {
+    basic.showNumber(ml.getCertainty(ml.event.Unknown))
+})
+```
+
+```package
+machine-learning=github:microbit-foundation/pxt-microbit-ml
+```

docs/ml_is_event_detected.md

@@ -0,0 +1,35 @@
+# 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 block compares the latest value of the estimated value to the action you choose. 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 `unknown` at the time the conditional statement is checked.
+
+```blocks
+basic.forever(function () {
+    if (ml.isDetected(ml.event.Unknown)) {
+        basic.showIcon(IconNames.Yes)
+    }
+})
+```
+
+```package
+machine-learning=github:microbit-foundation/pxt-microbit-ml
+```

docs/ml_on_event_start.md

@@ -0,0 +1,28 @@
+# on ML start
+
+Start an [event handler](/reference/event-handler) (part of the program that will run when something happens) This handler works when 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 uses the special `unknown` value and plays a musical melody in the background when no action has a certainty above the recognition point.
+
+```blocks
+ml.onStart(ml.event.Unknown, function () {
+    music._playDefaultBackground(music.builtInPlayableMelody(Melodies.Dadadadum), music.PlaybackMode.InBackground)
+})
+```
+
+```package
+machine-learning=github:microbit-foundation/pxt-microbit-ml
+```

docs/ml_on_event_stop.md

@@ -0,0 +1,30 @@
+# on ML stop
+
+Start an [event handler](/reference/event-handler) (part of the program that will run when something happens) This handler works when when the ML model’s estimated action changes to 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 uses the special `unknown` option and stops playing a musical melody when any other action has a certainty above the recognition point.
+
+```blocks
+ml.onStop(ml.event.Unknown, function () {
+    music.stopMelody(MelodyStopOptions.All)
+})
+```
+
+```package
+machine-learning=github:microbit-foundation/pxt-microbit-ml
+```

docs/ml_on_event_stop_detailed.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 when the ML model’s estimated action changes to 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.
+
+The event handler is passed a `duration` parameter. The duration is the 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.
+- **duration**: the [number](/types/number) of milliseconds the action was the estimated action.
+
+## Example
+
+This example uses the special `unknown` option and stops playing a musical melody when any other action has a certainty above the recognition point.
+
+```blocks
+ml.onStopDetailed(ml.event.Unknown, function (duration) {
+    basic.showNumber(duration / 1000)
+})
+```
+
+```package
+machine-learning=github:microbit-foundation/pxt-microbit-ml
+```

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.
+   */
   //% 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 = () => {
@@ -82,7 +87,7 @@ namespace ml {
   //% 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();
@@ -96,7 +101,7 @@ namespace ml {
   //% 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
@@ -112,7 +117,7 @@ namespace ml {
   //% 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();
@@ -125,7 +130,7 @@ namespace ml {
   //% 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) {