DOCS-2082: Add camera encoder gantry snippets (#3824)

components/camera/camera.go

@@ -88,17 +88,45 @@ type VideoSource interface {
 	projectorProvider
 	// Images is used for getting simultaneous images from different imagers,
 	// along with associated metadata (just timestamp for now). It's not for getting a time series of images from the same imager.
+	//
+	//    myCamera, err := camera.FromRobot(machine, "my_camera")
+	//
+	//    images, metadata, err := myCamera.Images(context.Background())
 	Images(ctx context.Context) ([]NamedImage, resource.ResponseMetadata, error)
 	// Stream returns a stream that makes a best effort to return consecutive images
 	// that may have a MIME type hint dictated in the context via gostream.WithMIMETypeHint.
+	//
+	//    myCamera, err := camera.FromRobot(machine, "my_camera")
+	//
+	//    // gets the stream from a camera
+	//    stream, err := myCamera.Stream(context.Background())
+	//
+	//    // gets an image from the camera stream
+	//    img, release, err := stream.Next(context.Background())
+	//    defer release()
 	Stream(ctx context.Context, errHandlers ...gostream.ErrorHandler) (gostream.VideoStream, error)
 
 	// NextPointCloud returns the next immediately available point cloud, not necessarily one
 	// a part of a sequence. In the future, there could be streaming of point clouds.
+	//
+	//    myCamera, err := camera.FromRobot(machine, "my_camera")
+	//
+	//    pointCloud, err := myCamera.NextPointCloud(context.Background())
 	NextPointCloud(ctx context.Context) (pointcloud.PointCloud, error)
 	// Properties returns properties that are intrinsic to the particular
 	// implementation of a camera
+	//
+	//    myCamera, err := camera.FromRobot(machine, "my_camera")
+	//
+	//    // gets the properties from a camera
+	//    properties, err := myCamera.Properties(context.Background())
 	Properties(ctx context.Context) (Properties, error)
+
+	// Close shuts down the resource and prevents further use
+	//
+	//    myCamera, err := camera.FromRobot(machine, "my_camera")
+	//
+	//    err = myCamera.Close(ctx)
 	Close(ctx context.Context) error
 }
 

components/encoder/encoder.go

@@ -62,12 +62,32 @@ type Encoder interface {
 	resource.Resource
 
 	// Position returns the current position in terms of ticks or degrees, and whether it is a relative or absolute position.
+	//
+	//    myEncoder, err := encoder.FromRobot(machine, "my_encoder")
+	//    if err != nil {
+	//      logger.Fatalf("cannot get encoder: %v", err)
+	//    }
+	//
+	//    // Get the position of the encoder in ticks
+	//    position, posType, err := myEncoder.Position(context.Background(), encoder.PositionTypeTicks, nil)
 	Position(ctx context.Context, positionType PositionType, extra map[string]interface{}) (float64, PositionType, error)
 
 	// ResetPosition sets the current position of the motor to be its new zero position.
+	//
+	//    myEncoder, err := encoder.FromRobot(machine, "my_encoder")
+	//    if err != nil {
+	//      logger.Fatalf("cannot get encoder: %v", err)
+	//    }
+	//
+	//    err = myEncoder.ResetPosition(context.Background(), nil)
 	ResetPosition(ctx context.Context, extra map[string]interface{}) error
 
 	// Properties returns a list of all the position types that are supported by a given encoder
+	//
+	//    myEncoder, err := encoder.FromRobot(machine, "my_encoder")
+	//
+	//    // Get whether the encoder returns position in ticks or degrees.
+	//    properties, err := myEncoder.Properties(context.Background(), nil)
 	Properties(ctx context.Context, extra map[string]interface{}) (Properties, error)
 }
 

components/gantry/gantry.go

@@ -48,16 +48,41 @@ type Gantry interface {
 	referenceframe.InputEnabled
 
 	// Position returns the position in meters
+	//
+	//    myGantry, err := gantry.FromRobot(machine, "my_gantry")
+	//
+	//    // Get the current positions of the axes of the gantry in millimeters.
+	//    position, err := myGantry.Position(context.Background(), nil)
 	Position(ctx context.Context, extra map[string]interface{}) ([]float64, error)
 
 	// MoveToPosition is in meters
 	// This will block until done or a new operation cancels this one
+	//
+	//    myGantry, err := gantry.FromRobot(machine, "my_gantry")
+	//
+	//    // Create a list of positions for the axes of the gantry to move to.
+	//    // Assume in this example that the gantry is multi-axis, with 3 axes.
+	//    examplePositions := []float64{1, 2, 3}
+	//
+	//    exampleSpeeds := []float64{3, 9, 12}
+	//
+	//    // Move the axes of the gantry to the positions specified.
+	//    myGantry.MoveToPosition(context.Background(), examplePositions, exampleSpeeds, nil)
 	MoveToPosition(ctx context.Context, positionsMm, speedsMmPerSec []float64, extra map[string]interface{}) error
 
 	// Lengths is the length of gantries in meters
+	//
+	//    myGantry, err := gantry.FromRobot(machine, "my_gantry")
+	//
+	//    // Get the lengths of the axes of the gantry in millimeters.
+	//    lengths_mm, err := myGantry.Lengths(context.Background(), nil)
 	Lengths(ctx context.Context, extra map[string]interface{}) ([]float64, error)
 
 	// Home runs the homing sequence of the gantry and returns true once completed
+	//
+	//    myGantry, err := gantry.FromRobot(machine, "my_gantry")
+	//
+	//    myGantry.Home(context.Background(), nil)
 	Home(ctx context.Context, extra map[string]interface{}) (bool, error)
 }