From 084d70bc3edb2a793b009e63c535ebbef4fa15a2 Mon Sep 17 00:00:00 2001
From: sky leilani <45158875+skyleilani@users.noreply.github.com>
Date: Mon, 13 May 2024 16:20:46 -0400
Subject: [PATCH] DOCS-2231: Review input controller, generic, and gripper
 snippets (#2860)

---
 docs/components/generic/_index.md          |  8 +-
 docs/components/gripper/_index.md          | 20 +----
 docs/components/input-controller/_index.md | 86 +++++-----------------
 3 files changed, 24 insertions(+), 90 deletions(-)

diff --git a/docs/components/generic/_index.md b/docs/components/generic/_index.md
index 455f2ed4b2..eed0444e1e 100644
--- a/docs/components/generic/_index.md
+++ b/docs/components/generic/_index.md
@@ -203,9 +203,7 @@ For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/
 - [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred.
 
 ```go {class="line-numbers linkable-line-numbers"}
-myGeneric, err := generic.FromRobot(robot, "my_generic_component")
-
-resp, err := myGeneric.DoCommand(ctx, map[string]interface{}{"command": "example"})
+resp, err := myGeneric.DoCommand(context.Background(), map[string]interface{}{"command": "example"})
 ```
 
 For more information, see the [Go SDK Code](https://github.com/viamrobotics/api/blob/main/component/generic/v1/generic_grpc.pb.go).
@@ -270,9 +268,7 @@ For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/
 - [(error)](https://pkg.go.dev/builtin#error) : An error, if one occurred. Close will never return an error for a generic resource.
 
 ```go {class="line-numbers linkable-line-numbers"}
-myGeneric, err := generic.FromRobot(robot, "my_generic")
-
-err := myGeneric.Close(ctx)
+err := myGeneric.Close(context.Background())
 ```
 
 For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/resource#TriviallyCloseable).
diff --git a/docs/components/gripper/_index.md b/docs/components/gripper/_index.md
index b9975d33ff..7af21bd55d 100644
--- a/docs/components/gripper/_index.md
+++ b/docs/components/gripper/_index.md
@@ -123,8 +123,6 @@ await my_gripper.open()
 For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/components/gripper#Gripper).
 
 ```go
-myGripper, err := gripper.FromRobot(robot, "my_gripper")
-
 // Open the gripper.
 err := myGripper.Open(context.Background(), nil)
 ```
@@ -172,8 +170,6 @@ grabbed = await my_gripper.grab()
 For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/components/gripper#Gripper).
 
 ```go
-myGripper, err := gripper.FromRobot(robot, "my_gripper")
-
 // Grab with the gripper.
 grabbed, err := myGripper.Grab(context.Background(), nil)
 ```
@@ -221,8 +217,6 @@ await my_gripper.stop()
 For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/components/gripper#Gripper).
 
 ```go
-myGripper, err := gripper.FromRobot(robot, "my_gripper")
-
 // Stop the gripper.
 err := myGripper.Stop(context.Background(), nil)
 ```
@@ -270,8 +264,6 @@ print('Moving:', moving)
 For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/resource#MovingCheckable).
 
 ```go
-myGripper, err := gripper.FromRobot(robot, "my_gripper")
-
 // Check whether the gripper is currently moving.
 moving, err := myGripper.IsMoving(context.Background())
 logger.Info("Is moving?")
@@ -325,14 +317,12 @@ if geometries:
 For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/resource#Shaped).
 
 ```go {class="line-numbers linkable-line-numbers"}
-myGripper, err := gripper.FromRobot(robot, "my_gripper")
-
 geometries, err := myGripper.Geometries(context.Background(), nil)
 
 if len(geometries) > 0 {
     // Get the center of the first geometry
     elem := geometries[0]
-    fmt.Println("Pose of the first geometry's center point:", elem.center)
+    fmt.Println("Pose of the first geometry's center point:", elem.Pose())
 }
 ```
 
@@ -382,9 +372,7 @@ For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/
 - [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred.
 
 ```go {class="line-numbers linkable-line-numbers"}
-myGripper, err := gripper.FromRobot(robot, "my_gripper")
-
-resp, err := myGripper.DoCommand(ctx, map[string]interface{}{"command": "example"})
+resp, err := myGripper.DoCommand(context.Background(), map[string]interface{}{"command": "example"})
 ```
 
 For more information, see the [Go SDK Code](https://github.com/viamrobotics/api/blob/main/component/gripper/v1/gripper_grpc.pb.go).
@@ -427,9 +415,7 @@ For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/
 - [(error)](https://pkg.go.dev/builtin#error) : An error, if one occurred.
 
 ```go {class="line-numbers linkable-line-numbers"}
-myGripper, err := gripper.FromRobot(robot, "my_gripper")
-
-err := myGripper.Close(ctx)
+err := myGripper.Close(context.Background())
 ```
 
 For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/resource#Resource).
diff --git a/docs/components/input-controller/_index.md b/docs/components/input-controller/_index.md
index b14fcaa8d3..4c03f61002 100644
--- a/docs/components/input-controller/_index.md
+++ b/docs/components/input-controller/_index.md
@@ -192,54 +192,22 @@ For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/c
 
 ```go {class="line-numbers linkable-line-numbers"}
 
-// Define a function that handles the controller.
-func handleController(controller input.Controller) {
-
-    // Define a function to handle pressing the Start Menu Button "ButtonStart" on your controller, logging the start time.
-    printStartTime := func(ctx context.Context, event input.Event) {
-        logger.Info("Start Menu Button was pressed at this time: %v", event.Time)
-    }
-
-    // Define the EventType "ButtonPress" to serve as the trigger for printStartTime.
-    triggers := [1]input.EventType{input.ButtonPress}
-
-    // Get the controller's Controls.
-    controls, err := controller.Controls(context.Background(), nil)
-
-    // If the "ButtonStart" Control is found, register the function printStartTime to fire when "ButtonStart" has the event "ButtonPress" occur.
-    if slices.Contains(controls, Control.ButtonStart) {
-        err := controller.RegisterControlCallback(context.Background(), Control: input.ButtonStart, triggers, printStartTime, nil)
-    }
-     else {
-        logger.Fatalf("Oops! Couldn't find the start button control! Is your controller connected?")
-    }
+// Define a function to handle pressing the Start Menu button, "ButtonStart", on your controller and logging the start time
+printStartTime := func(ctx context.Context, event input.Event) {
+    logger.Info("Start Menu Button was pressed at this time: %v", event.Time)
 }
 
-func main() {
-    utils.ContextualMain(mainWithArgs, logging.NewLogger("client"))
-}
-
-
-func mainWithArgs(ctx context.Context, args []string, logger logging.Logger) (err error) {
-    // ... < INSERT CONNECTION CODE FROM MACHINE'S CODE SAMPLE TAB >
-
-    // Get the controller from the machine.
-    myController, err := input.FromRobot(myRobotWithController, "my_controller")
-
-    // Run the handleController function.
-    err := HandleController(myController)
-
-    // Delay closing your connection to your machine.
-    err = myRobotWithController.Start(ctx)
-    defer myRobotWithController.Close(ctx)
-
-    // Wait to exit mainWithArgs() until Context is Done.
-    <-ctx.Done()
+// Define the EventType "ButtonPress" to serve as the trigger for printStartTime.
+triggers := []input.EventType{input.ButtonPress}
 
-    // ... < INSERT ANY OTHER CODE FOR MAIN FUNCTION >
+// Get the controller's Controls.
+controls, err := controller.Controls(ctx, nil)
 
-    return nil
+// If the "ButtonStart" Control is found, register the function printStartTime to fire when "ButtonStart" has the event "ButtonPress" occur.
+if !slices.Contains(controls, input.ButtonStart) {
+    return errors.New("button `ButtonStart` not found; controller may be disconnected")
 }
+    myController.RegisterControlCallback(context.Background(), input.ButtonStart, triggers, printStartTime, nil)
 ```
 
 {{% /tab %}}
@@ -247,7 +215,7 @@ func mainWithArgs(ctx context.Context, args []string, logger logging.Logger) (er
 
 ### GetEvents
 
-This method returns the current state of the controller as a map of [Event Objects](#event-object), representing the most recent event that has occured on each available [Control](#control-field).
+This method returns the current state of the controller as a map of [Event Objects](#event-object), representing the most recent event that has occurred on each available [Control](#control-field).
 
 {{< tabs >}}
 {{% tab name="Python" %}}
@@ -291,14 +259,8 @@ print(f"Recent Events:\n{recent_events}")
 For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/components/input#Controller).
 
 ```go {class="line-numbers linkable-line-numbers"}
-// Get the controller from the machine.
-myController, err := input.FromRobot(myRobotWithController, "my_controller")
-
 // Get the most recent Event for each Control.
 recent_events, err := myController.Events(context.Background(), nil)
-
-// Log the most recent Event for each Control.
-logger.Info("Recent Events: %v", recent_events)
 ```
 
 {{% /tab %}}
@@ -350,15 +312,8 @@ print(f"Controls:\n{controls}")
 For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/components/input#Controller).
 
 ```go {class="line-numbers linkable-line-numbers"}
-// Get the controller from the machine.
-myController, err := input.FromRobot(myRobotWithController, "my_controller")
-
 // Get the list of Controls provided by the controller.
 controls, err := myController.Controls(context.Background(), nil)
-
-// Log the list of Controls provided by the controller.
-logger.Info("Controls:")
-logger.Info(controls)
 ```
 
 {{% /tab %}}
@@ -416,14 +371,16 @@ For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/c
 // Define a "Button is Pressed" event for the control ButtonStart.
 buttonIsPressedEvent := input.Event{Time: time.Now(), Event: input.ButtonPress, Control: input.ButtonStart, Value: 1.0}
 
-// Trigger the event on your controller.
-err := myController.TriggerEvent(ctx Context.background(), buttonIsPressedEvent, nil)
+triggerableController, ok := myController.(input.Triggerable)
+if !ok {
+    logger.Fatalf("this controller does not support trigger events")
+}
 
-// Log any errors that occur.
+// Trigger the event on your controller.
+err = triggerableController.TriggerEvent(ctx, buttonIsPressedEvent, nil)
 if err != nil {
   logger.Fatalf("cannot trigger event on controller: %v", err)
 }
-
 ```
 
 {{% /tab %}}
@@ -533,9 +490,6 @@ For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/
 - [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred.
 
 ```go {class="line-numbers linkable-line-numbers"}
-// Get the controller from the machine.
-myController, err := input.FromRobot(myRobotWithController, "my_controller")
-
 command := map[string]interface{}{"cmd": "test", "data1": 500}
 result, err := myController.DoCommand(context.Background(), command)
 ```
@@ -580,9 +534,7 @@ For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/
 - [(error)](https://pkg.go.dev/builtin#error) : An error, if one occurred.
 
 ```go {class="line-numbers linkable-line-numbers"}
-myController, err := input.FromRobot(myRobotWithController, "my_controller")
-
-err := myController.Close(ctx)
+err := myController.Close(context.Background())
 ```
 
 For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/resource#Resource).