Doc comment updates

Signed-off-by: Kimmo Lehto <[email protected]>

client.go

@@ -9,7 +9,6 @@ import (
 	"sync"
 
 	"github.com/k0sproject/rig/exec"
-	"github.com/k0sproject/rig/initsystem"
 	"github.com/k0sproject/rig/log"
 	"github.com/k0sproject/rig/os"
 	"github.com/k0sproject/rig/packagemanager"
@@ -171,7 +170,13 @@ func (c *Client) setup(opts ...Option) error {
 	return c.initErr
 }
 
-// Service returns a Service object for the named service using the host's init system.
+// Service returns a manager for a named service on the remote host using
+// the host's init system if one can be detected. This can be used to
+// start, stop, restart, and check the status of services.
+//
+// You most likely need to use this with Sudo:
+//
+//	service, err := client.Sudo().Service("nginx")
 func (c *Client) Service(name string) (*Service, error) {
 	is, err := c.InitSystemService.GetServiceManager()
 	if err != nil {
@@ -257,21 +262,16 @@ func (c *Client) ExecInteractive(cmd string, stdin io.Reader, stdout, stderr io.
 }
 
 // FS returns a fs.FS compatible filesystem interface for accessing files on the host.
-// If the filesystem can't be accessed, a filesystem that returns an error for all operations is returned.
-// If you need to handle the error, you can use client.RemoteFSService.GetFS() (FS, error) directly.
+//
+// If the filesystem can't be accessed, a filesystem that returns an error for all operations is returned
+// instead. If you need to handle the error, you can use c.RemoteFSService.GetFS() directly.
 func (c *Client) FS() remotefs.FS {
 	return c.RemoteFSService.FS()
 }
 
-// InitSystem returns a ServiceManager for the host's init system.
-// If the init system can't be determined, a ServiceManager that returns an error for all operations is returned.
-// If you need to handle the error, you can use client.InitSystemService.GetServiceManager() (initsystem.ServiceManager, error) directly.
-func (c *Client) InitSystem() initsystem.ServiceManager {
-	return c.InitSystemService.ServiceManager()
-}
-
-// PackageManager returns a PackageManager for the host's package manager
-// If the package manager can't be determined, a PackageManager that returns an error for all operations is returned.
+// PackageManager for the host's operating system. This can be used to install or remove packages.
+//
+// If a known package manager can't be detected, a PackageManager that returns an error for all operations is returned.
 // If you need to handle the error, you can use client.PackageManagerService.GetPackageManager() (packagemanager.PackageManager, error) directly.
 func (c *Client) PackageManager() packagemanager.PackageManager {
 	return c.PackageManagerService.PackageManager()

exec/exec.go

@@ -1,4 +1,4 @@
-// Package exec provides helpers for setting execution options for commands
+// Package exec provides command exeecution capabilities for rig connections.
 package exec
 
 // DisableRedact will disable all redaction of sensitive data.

openssh/connection.go

@@ -1,4 +1,4 @@
-// Package openssh provides a rig protocol implementation that uses the system openssh client "ssh" to connect to remote hosts.
+// Package openssh provides a rig protocol implementation that uses the system's openssh client "ssh" to connect to remote hosts.
 package openssh
 
 import (
@@ -40,6 +40,7 @@ type Connection struct {
 
 // NewConnection creates a new OpenSSH connection. Error is currently always nil.
 func NewConnection(cfg Config) (*Connection, error) {
+	cfg.SetDefaults()
 	return &Connection{Config: cfg}, nil
 }
 
@@ -237,7 +238,7 @@ func (c *Connection) StartProcess(ctx context.Context, cmdStr string, stdin io.R
 	return cmd, nil
 }
 
-// ExecInteractive executes an interactive command on the remote host, streaming stdin, stdout and stderr.
+// ExecInteractive executes a command on the host and passes stdin/stdout/stderr as-is to the session.
 func (c *Connection) ExecInteractive(cmdStr string, stdin io.Reader, stdout, stderr io.Writer) error {
 	cmd, err := c.StartProcess(context.Background(), cmdStr, stdin, stdout, stderr)
 	if err != nil {

plumbing/lazyservice.go

@@ -1,4 +1,4 @@
-// Package plumbing defines a generic types for the dependency injection mechanics in rig.
+// Package plumbing defines generic types for the dependency injection mechanics in rig.
 package plumbing
 
 import (

protocol/connection.go

@@ -1,4 +1,4 @@
-// Package protocol : contains the interfaces for the protocol implementations
+// Package protocol contains the interfaces for the protocol implementations
 package protocol
 
 import (

service.go

@@ -21,7 +21,7 @@ const (
 // ErrEmptyResult is returned when a command returns an empty result.
 var ErrEmptyResult = errors.New("empty result")
 
-// Service is an interface for managing a service on an initsystem.
+// Service running on a host.
 type Service struct {
 	runner  exec.ContextRunner
 	name    string

ssh/connection.go

@@ -49,6 +49,7 @@ type Connection struct {
 
 // NewConnection creates a new SSH connection. Error is currently always nil.
 func NewConnection(cfg Config) (*Connection, error) {
+	cfg.SetDefaults()
 	return &Connection{Config: cfg}, nil
 }
 
@@ -537,7 +538,7 @@ func (c *Connection) StartProcess(ctx context.Context, cmd string, stdin io.Read
 	return session, nil
 }
 
-// ExecInteractive executes a command on the host and copies stdin/stdout/stderr from local host.
+// ExecInteractive executes a command on the host and passes stdin/stdout/stderr as-is to the session.
 func (c *Connection) ExecInteractive(cmd string, stdin io.Reader, stdout, stderr io.Writer) error {
 	session, err := c.client.NewSession()
 	if err != nil {

winrm/connection.go

@@ -43,6 +43,7 @@ type dialFunc func(network, addr string) (net.Conn, error)
 
 // NewConnection creates a new WinRM connection. Error is currently always nil.
 func NewConnection(cfg Config) (*Connection, error) {
+	cfg.SetDefaults()
 	return &Connection{Config: cfg}, nil
 }
 
@@ -277,7 +278,7 @@ func (c *Connection) StartProcess(ctx context.Context, cmd string, stdin io.Read
 	return res, nil
 }
 
-// ExecInteractive executes a command on the host and copies stdin/stdout/stderr from local host.
+// ExecInteractive executes a command on the host and passes stdin/stdout/stderr as-is to the session.
 func (c *Connection) ExecInteractive(cmd string, stdin io.Reader, stdout, stderr io.Writer) error {
 	if cmd == "" {
 		cmd = "cmd.exe"