From 96a2e125e6b9e64ed48e6423e309ba22ea02e93e Mon Sep 17 00:00:00 2001
From: Jason Lunz <znull@github.com>
Date: Thu, 16 Dec 2021 16:37:26 -0700
Subject: [PATCH] document the codespaceSSHConfig struct

---
 pkg/cmd/codespace/ssh.go | 19 +++++++++++++++----
 1 file changed, 15 insertions(+), 4 deletions(-)

diff --git a/pkg/cmd/codespace/ssh.go b/pkg/cmd/codespace/ssh.go
index 3c729740d..153cb884c 100644
--- a/pkg/cmd/codespace/ssh.go
+++ b/pkg/cmd/codespace/ssh.go
@@ -238,11 +238,22 @@ func (a *App) ListOpensshConfig(ctx context.Context, opts configOptions) error {
 	return nil
 }
 
+// codespaceSSHConfig contains values needed to write an openssh host
+// configuration for a single codespace. For example:
+//
+// Host {{Name}}.{{EscapedRef}
+// User {{SSHUser}
+// ProxyCommand {{GHExec}} cs ssh -c {{Name}} --stdio
+//
+// EscapedRef is included in the name to help distinguish between codespaces
+// when tab-completing ssh hostnames. '/' characters in EscapedRef are
+// flattened to '-' to prevent problems with tab completion or when the
+// hostname appears in ControlMaster socket paths.
 type codespaceSSHConfig struct {
-	Name       string
-	EscapedRef string
-	SSHUser    string
-	GHExec     string
+	Name       string // the codespace name, passed to `ssh -c`
+	EscapedRef string // the currently checked-out branch
+	SSHUser    string // the remote ssh username
+	GHExec     string // path used for invoking the current `gh` binary
 }
 
 func openSSHSession(ctx context.Context, a *App, csName string, liveshareLogger *log.Logger) (*liveshare.Session, error) {