From 7618024294d1070934574337ed7e884e22020bfe Mon Sep 17 00:00:00 2001
From: Kynan Ware <47394200+BagToad@users.noreply.github.com>
Date: Wed, 4 Mar 2026 16:08:04 -0700
Subject: [PATCH] Add godoc comments to exported symbols in pkg/cmd/codespace

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 pkg/cmd/codespace/codespace_selector.go | 3 +++
 pkg/cmd/codespace/common.go             | 6 ++++++
 pkg/cmd/codespace/create.go             | 7 +++++++
 pkg/cmd/codespace/delete.go             | 2 ++
 pkg/cmd/codespace/jupyter.go            | 1 +
 pkg/cmd/codespace/list.go               | 1 +
 pkg/cmd/codespace/logs.go               | 1 +
 pkg/cmd/codespace/ports.go              | 5 +++++
 pkg/cmd/codespace/rebuild.go            | 1 +
 pkg/cmd/codespace/root.go               | 1 +
 pkg/cmd/codespace/ssh.go                | 2 ++
 pkg/cmd/codespace/stop.go               | 1 +
 pkg/cmd/codespace/view.go               | 1 +
 13 files changed, 32 insertions(+)

diff --git a/pkg/cmd/codespace/codespace_selector.go b/pkg/cmd/codespace/codespace_selector.go
index a51e42b6f..387ca1ecf 100644
--- a/pkg/cmd/codespace/codespace_selector.go
+++ b/pkg/cmd/codespace/codespace_selector.go
@@ -10,6 +10,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// CodespaceSelector selects a codespace based on command-line flags.
 type CodespaceSelector struct {
 	api apiClient
 
@@ -34,6 +35,7 @@ func AddCodespaceSelector(cmd *cobra.Command, api apiClient) *CodespaceSelector
 	return cs
 }
 
+// Select returns a fully resolved codespace based on the selector's flags.
 func (cs *CodespaceSelector) Select(ctx context.Context) (codespace *api.Codespace, err error) {
 	if cs.codespaceName != "" {
 		codespace, err = cs.api.GetCodespace(ctx, cs.codespaceName, true)
@@ -62,6 +64,7 @@ func (cs *CodespaceSelector) Select(ctx context.Context) (codespace *api.Codespa
 	return codespace, nil
 }
 
+// SelectName returns the name of a codespace based on the selector's flags.
 func (cs *CodespaceSelector) SelectName(ctx context.Context) (string, error) {
 	if cs.codespaceName != "" {
 		return cs.codespaceName, nil
diff --git a/pkg/cmd/codespace/common.go b/pkg/cmd/codespace/common.go
index e56e6c0b8..0ac66eed0 100644
--- a/pkg/cmd/codespace/common.go
+++ b/pkg/cmd/codespace/common.go
@@ -27,6 +27,7 @@ type executable interface {
 	Executable() string
 }
 
+// App holds the state and dependencies for codespace commands.
 type App struct {
 	io         *iostreams.IOStreams
 	apiClient  apiClient
@@ -36,6 +37,7 @@ type App struct {
 	remotes    func() (clicontext.Remotes, error)
 }
 
+// NewApp creates a new App with the given dependencies.
 func NewApp(io *iostreams.IOStreams, exe executable, apiClient apiClient, browser browser.Browser, remotes func() (clicontext.Remotes, error)) *App {
 	errLogger := log.New(io.ErrOut, "", 0)
 
@@ -59,6 +61,7 @@ func (a *App) StopProgressIndicator() {
 	a.io.StopProgressIndicator()
 }
 
+// RunWithProgress runs a function while displaying a progress indicator with a label.
 func (a *App) RunWithProgress(label string, run func() error) error {
 	return a.io.RunWithProgress(label, run)
 }
@@ -146,10 +149,12 @@ func safeClose(closer io.Closer, err *error) {
 // It is not portable to assume stdin/stdout are fds 0 and 1.
 var hasTTY = term.IsTerminal(int(os.Stdin.Fd())) && term.IsTerminal(int(os.Stdout.Fd()))
 
+// SurveyPrompter is an interface for prompting survey questions.
 type SurveyPrompter interface {
 	Ask(qs []*survey.Question, response interface{}) error
 }
 
+// Prompter implements SurveyPrompter using the terminal.
 type Prompter struct{}
 
 // ask asks survey questions on the terminal, using standard options.
@@ -176,6 +181,7 @@ func (p *Prompter) Ask(qs []*survey.Question, response interface{}) error {
 	return err
 }
 
+// ErrTooManyArgs is returned when a command receives unexpected arguments.
 var ErrTooManyArgs = errors.New("the command accepts no arguments")
 
 func noArgsConstraint(cmd *cobra.Command, args []string) error {
diff --git a/pkg/cmd/codespace/create.go b/pkg/cmd/codespace/create.go
index bd2eb4623..ec63ed9ca 100644
--- a/pkg/cmd/codespace/create.go
+++ b/pkg/cmd/codespace/create.go
@@ -16,6 +16,7 @@ import (
 )
 
 const (
+	// DEVCONTAINER_PROMPT_DEFAULT is the label for the default devcontainer option.
 	DEVCONTAINER_PROMPT_DEFAULT = "Default Codespaces configuration"
 )
 
@@ -29,13 +30,16 @@ const (
 )
 
 var (
+	// DEFAULT_DEVCONTAINER_DEFINITIONS lists the standard devcontainer.json file paths.
 	DEFAULT_DEVCONTAINER_DEFINITIONS = []string{".devcontainer.json", ".devcontainer/devcontainer.json"}
 )
 
+// NullableDuration is an optional duration value used for command flags.
 type NullableDuration struct {
 	*time.Duration
 }
 
+// String returns the string representation of the duration, or empty if nil.
 func (d *NullableDuration) String() string {
 	if d.Duration != nil {
 		return d.Duration.String()
@@ -44,6 +48,7 @@ func (d *NullableDuration) String() string {
 	return ""
 }
 
+// Set parses a duration string and sets the value.
 func (d *NullableDuration) Set(str string) error {
 	duration, err := time.ParseDuration(str)
 	if err != nil {
@@ -53,10 +58,12 @@ func (d *NullableDuration) Set(str string) error {
 	return nil
 }
 
+// Type returns the flag type name for NullableDuration.
 func (d *NullableDuration) Type() string {
 	return "duration"
 }
 
+// Minutes returns the duration in minutes as an int pointer, or nil if unset.
 func (d *NullableDuration) Minutes() *int {
 	if d.Duration != nil {
 		retentionMinutes := int(d.Duration.Minutes())
diff --git a/pkg/cmd/codespace/delete.go b/pkg/cmd/codespace/delete.go
index 5da24a634..51fb2be52 100644
--- a/pkg/cmd/codespace/delete.go
+++ b/pkg/cmd/codespace/delete.go
@@ -89,6 +89,7 @@ func newDeleteCmd(app *App) *cobra.Command {
 	return deleteCmd
 }
 
+// Delete removes one or more codespaces based on the provided options.
 func (a *App) Delete(ctx context.Context, opts deleteOptions) (err error) {
 	var codespaces []*api.Codespace
 	nameFilter := opts.codespaceName
@@ -219,6 +220,7 @@ func confirmDeletion(p prompter, apiCodespace *api.Codespace, isInteractive bool
 
 type surveyPrompter struct{}
 
+// Confirm prompts the user for a yes/no confirmation.
 func (p *surveyPrompter) Confirm(message string) (bool, error) {
 	prompter := &Prompter{}
 	var confirmed struct {
diff --git a/pkg/cmd/codespace/jupyter.go b/pkg/cmd/codespace/jupyter.go
index a27a34271..a3dea057c 100644
--- a/pkg/cmd/codespace/jupyter.go
+++ b/pkg/cmd/codespace/jupyter.go
@@ -29,6 +29,7 @@ func newJupyterCmd(app *App) *cobra.Command {
 	return jupyterCmd
 }
 
+// Jupyter opens JupyterLab in a browser connected to a codespace.
 func (a *App) Jupyter(ctx context.Context, selector *CodespaceSelector) (err error) {
 	// Ensure all child tasks (e.g. port forwarding) terminate before return.
 	ctx, cancel := context.WithCancel(ctx)
diff --git a/pkg/cmd/codespace/list.go b/pkg/cmd/codespace/list.go
index 238c4a6a7..35ed9305d 100644
--- a/pkg/cmd/codespace/list.go
+++ b/pkg/cmd/codespace/list.go
@@ -76,6 +76,7 @@ func newListCmd(app *App) *cobra.Command {
 	return listCmd
 }
 
+// List displays the user's codespaces in a table or JSON format.
 func (a *App) List(ctx context.Context, opts *listOptions, exporter cmdutil.Exporter) error {
 	if opts.useWeb && opts.repo == "" {
 		return a.browser.Browse(fmt.Sprintf("%s/codespaces", a.apiClient.ServerURL()))
diff --git a/pkg/cmd/codespace/logs.go b/pkg/cmd/codespace/logs.go
index 37b301217..234a9ce08 100644
--- a/pkg/cmd/codespace/logs.go
+++ b/pkg/cmd/codespace/logs.go
@@ -32,6 +32,7 @@ func newLogsCmd(app *App) *cobra.Command {
 	return logsCmd
 }
 
+// Logs streams the creation log from a codespace.
 func (a *App) Logs(ctx context.Context, selector *CodespaceSelector, follow bool) (err error) {
 	// Ensure all child tasks (port forwarding, remote exec) terminate before return.
 	ctx, cancel := context.WithCancel(ctx)
diff --git a/pkg/cmd/codespace/ports.go b/pkg/cmd/codespace/ports.go
index ef386dc86..520c2a5f2 100644
--- a/pkg/cmd/codespace/ports.go
+++ b/pkg/cmd/codespace/ports.go
@@ -130,10 +130,12 @@ type portInfo struct {
 	devContainer *devContainer
 }
 
+// BrowseURL returns the browser-accessible URL for the port.
 func (pi *portInfo) BrowseURL() string {
 	return fmt.Sprintf("https://%s-%d.app.github.dev", pi.codespace.Name, pi.Port.PortNumber)
 }
 
+// Label returns the devcontainer label for the port, if any.
 func (pi *portInfo) Label() string {
 	if pi.devContainer != nil {
 		portStr := strconv.Itoa(int(pi.Port.PortNumber))
@@ -151,6 +153,7 @@ var portFields = []string{
 	"browseUrl",
 }
 
+// ExportData returns port information as a map for JSON export.
 func (pi *portInfo) ExportData(fields []string) map[string]interface{} {
 	data := map[string]interface{}{}
 
@@ -230,6 +233,7 @@ func newPortsVisibilityCmd(app *App, selector *CodespaceSelector) *cobra.Command
 	}
 }
 
+// UpdatePortVisibility changes the visibility of forwarded ports in a codespace.
 func (a *App) UpdatePortVisibility(ctx context.Context, selector *CodespaceSelector, args []string) (err error) {
 	ports, err := a.parsePortVisibilities(args)
 	if err != nil {
@@ -309,6 +313,7 @@ func newPortsForwardCmd(app *App, selector *CodespaceSelector) *cobra.Command {
 	}
 }
 
+// ForwardPorts forwards remote codespace ports to local addresses.
 func (a *App) ForwardPorts(ctx context.Context, selector *CodespaceSelector, ports []string) (err error) {
 	portPairs, err := getPortPairs(ports)
 	if err != nil {
diff --git a/pkg/cmd/codespace/rebuild.go b/pkg/cmd/codespace/rebuild.go
index a7a9b9ba0..ff528d932 100644
--- a/pkg/cmd/codespace/rebuild.go
+++ b/pkg/cmd/codespace/rebuild.go
@@ -40,6 +40,7 @@ func newRebuildCmd(app *App) *cobra.Command {
 	return rebuildCmd
 }
 
+// Rebuild recreates the container for a codespace.
 func (a *App) Rebuild(ctx context.Context, selector *CodespaceSelector, full bool) (err error) {
 	ctx, cancel := context.WithCancel(ctx)
 	defer cancel()
diff --git a/pkg/cmd/codespace/root.go b/pkg/cmd/codespace/root.go
index d1675a8f7..900553361 100644
--- a/pkg/cmd/codespace/root.go
+++ b/pkg/cmd/codespace/root.go
@@ -7,6 +7,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// NewCmdCodespace creates the top-level codespace command.
 func NewCmdCodespace(f *cmdutil.Factory) *cobra.Command {
 	root := &cobra.Command{
 		Use:     "codespace",
diff --git a/pkg/cmd/codespace/ssh.go b/pkg/cmd/codespace/ssh.go
index cd90541f2..85f372d23 100644
--- a/pkg/cmd/codespace/ssh.go
+++ b/pkg/cmd/codespace/ssh.go
@@ -148,6 +148,7 @@ type combinedReadWriteHalfCloser struct {
 	io.WriteCloser
 }
 
+// Close closes both the read and write halves of the connection.
 func (crwc *combinedReadWriteHalfCloser) Close() error {
 	werr := crwc.WriteCloser.Close()
 	rerr := crwc.ReadCloser.Close()
@@ -157,6 +158,7 @@ func (crwc *combinedReadWriteHalfCloser) Close() error {
 	return rerr
 }
 
+// CloseWrite closes the write half of the connection.
 func (crwc *combinedReadWriteHalfCloser) CloseWrite() error {
 	return crwc.WriteCloser.Close()
 }
diff --git a/pkg/cmd/codespace/stop.go b/pkg/cmd/codespace/stop.go
index c2b675033..677022c2b 100644
--- a/pkg/cmd/codespace/stop.go
+++ b/pkg/cmd/codespace/stop.go
@@ -37,6 +37,7 @@ func newStopCmd(app *App) *cobra.Command {
 	return stopCmd
 }
 
+// StopCodespace stops a running codespace.
 func (a *App) StopCodespace(ctx context.Context, opts *stopOptions) error {
 	var (
 		codespaceName = opts.selector.codespaceName
diff --git a/pkg/cmd/codespace/view.go b/pkg/cmd/codespace/view.go
index 0bcbc8b5b..c5a67d731 100644
--- a/pkg/cmd/codespace/view.go
+++ b/pkg/cmd/codespace/view.go
@@ -52,6 +52,7 @@ func newViewCmd(app *App) *cobra.Command {
 	return viewCmd
 }
 
+// ViewCodespace displays details about a selected codespace.
 func (a *App) ViewCodespace(ctx context.Context, opts *viewOptions) error {
 	// If we are in a codespace and a codespace name wasn't provided, show the details for the codespace we are connected to
 	if (os.Getenv("CODESPACES") == "true") && opts.selector.codespaceName == "" {