[v15] Move documentation from tshd/types.ts to proto files (#40006)

* Move comments from `tshd/types.ts` to proto files

* Simplify LoggedInUser docs

* Remove "`"

proto/teleport/lib/teleterm/v1/app.proto

@@ -38,8 +38,16 @@ message App {
   // aws_console is true if this app is AWS management console.
   bool aws_console = 5;
   // public_addr is the public address the application is accessible at.
+  // By default, it is a subdomain of the cluster (e.g., dumper.example.com).
+  // Optionally, it can be overridden (by the 'public_addr' field in the app config)
+  // with an address available on the internet.
+  //
+  // Always empty for SAML applications.
   string public_addr = 6;
   // friendly_name is a user readable name of the app.
+  // Right now, it is set only for Okta applications.
+  // It is constructed from a label value.
+  // See more in api/types/resource.go.
   string friendly_name = 7;
   // saml_app is true if the application is a SAML Application (Service Provider).
   bool saml_app = 8;

proto/teleport/lib/teleterm/v1/cluster.proto

@@ -22,20 +22,31 @@ package teleport.lib.teleterm.v1;
 
 option go_package = "github.com/gravitational/teleport/gen/proto/go/teleport/lib/teleterm/v1;teletermv1";
 
-// Cluster describes cluster fields
+// Cluster describes cluster fields.
 message Cluster {
-  // uri is the cluster resource URI
+  // uri is the cluster resource URI.
+  // For root clusters, it has the form of /clusters/:rootClusterId where rootClusterId is the
+  // name of the profile, that is the hostname of the proxy used to connect to the root cluster.
+  // rootClusterId is not equal to the name of the root cluster.
+  //
+  // For leaf clusters, it has the form of /clusters/:rootClusterId/leaves/:leafClusterId where
+  // leafClusterId is equal to the name property of the cluster.
   string uri = 1;
   // name is used throughout the Teleport Connect codebase as the cluster name.
   string name = 2;
-  // proxy address (only for root clusters)
+  // proxy_host is address of the proxy used to connect to this cluster.
+  // Always includes port number. Present only for root clusters.
+  //
+  // Example: "teleport-14-ent.example.com:3090"
   string proxy_host = 3;
   // connected indicates if connection to the cluster can be established, that is if we have a
   // cert for the cluster that hasn't expired
   bool connected = 4;
   // leaf indicates if this is a leaf cluster
   bool leaf = 5;
-  // User is the cluster access control list of the logged-in user
+  // logged_in_user is present if the user has logged in to the cluster at least once, even
+  // if the cert has since expired. If the cluster was added to the app but the
+  // user is yet to log in, logged_in_user is not present.
   LoggedInUser logged_in_user = 7;
   // features describes the auth servers features.
   // Only present when detailed information is queried from the auth server.
@@ -57,7 +68,8 @@ message LoggedInUser {
   repeated string roles = 2;
   // ssh_logins is the user ssh logins
   repeated string ssh_logins = 3;
-  // acl is the user acl
+  // acl is a user access control list.
+  // It is available only after the cluster details are fetched, as it is not stored on disk.
   ACL acl = 4;
   // active_requests is an array of request-id strings of active requests
   repeated string active_requests = 5;

proto/teleport/lib/teleterm/v1/gateway.proto

@@ -62,13 +62,21 @@ message Gateway {
 // GatewayCLICommand represents a command that the user can execute to connect to the gateway
 // resource. It is a direct translation of os.exec.Cmd.
 message GatewayCLICommand {
+  // path is the absolute path to the CLI client of a gateway if the client is
+  // in PATH. Otherwise, the name of the program we were trying to find.
   string path = 1;
+  // args is a list containing the name of the program as the first element
+  // and the actual args as the other elements
   repeated string args = 2;
+  // env is a list of env vars that need to be set for the command
+  // invocation. The elements of the list are in the format of NAME=value.
   repeated string env = 3;
   // preview is used to show the user what command will be executed before they decide to run it.
   // It's like os.exec.Cmd.String with two exceptions:
   //
   // 1) It is prepended with Cmd.Env.
   // 2) The command name is relative and not absolute.
+  //
+  // Should not be used to execute anything in the shell.
   string preview = 4;
 }

web/packages/teleterm/src/services/tshd/types.ts

@@ -67,54 +67,14 @@ export interface Server extends apiServer.Server {
 
 export interface App extends apiApp.App {
   uri: uri.AppUri;
-  /** Name of the application. */
-  name: string;
-  /** URI and port the target application is available at. */
-  endpointUri: string;
-  /** Description of the application. */
-  desc: string;
-  /** Indicates if the application is an AWS management console. */
-  awsConsole: boolean;
-  /**
-   * The application public address.
-   * By default, it is a subdomain of the cluster (e.g., dumper.example.com).
-   * Optionally, it can be overridden (by the 'public_addr' field in the app config)
-   * with an address available on the internet.
-   *
-   * Always empty for SAML applications.
-   */
-  publicAddr: string;
-  /**
-   * Right now, `friendlyName` is set only for Okta applications.
-   * It is constructed from a label value.
-   * See more in api/types/resource.go.
-   */
-  friendlyName: string;
-  /** Indicates if the application is a SAML Application (SAML IdP Service Provider). */
-  samlApp: boolean;
 }
 
 export interface Gateway extends apiGateway.Gateway {
   uri: uri.GatewayUri;
   targetUri: uri.GatewayTargetUri;
-  // The type of gatewayCliCommand was repeated here just to refer to the type with the JSDoc.
   gatewayCliCommand: GatewayCLICommand;
 }
 
-/**
- * GatewayCLICommand follows the API of os.exec.Cmd from Go.
- * https://pkg.go.dev/os/exec#Cmd
- *
- * @property {string} path - The absolute path to the CLI client of a gateway if the client is
- * in PATH. Otherwise, the name of the program we were trying to find.
- * @property {string[]} argsList - A list containing the name of the program as the first element
- * and the actual args as the other elements.
- * @property {string[]} envList – A list of env vars that need to be set for the command
- * invocation. The elements of the list are in the format of NAME=value.
- * @property {string} preview - A string showing how the invocation of the command would look like
- * if the user was to invoke it manually from the terminal. Should not be actually used to execute
- * anything in the shell.
- */
 export type GatewayCLICommand = apiGateway.GatewayCLICommand;
 
 export type AccessRequest = apiAccessRequest.AccessRequest;
@@ -160,46 +120,12 @@ export interface Database extends apiDb.Database {
 }
 
 export interface Cluster extends apiCluster.Cluster {
-  /**
-   * The URI of the cluster.
-   *
-   * For root clusters, it has the form of `/clusters/:rootClusterId` where `rootClusterId` is the
-   * name of the profile, that is the hostname of the proxy used to connect to the root cluster.
-   * `rootClusterId` is not equal to the name of the root cluster.
-   *
-   * For leaf clusters, it has the form of `/clusters/:rootClusterId/leaves/:leafClusterId` where
-   * `leafClusterId` is equal to the `name` property of the cluster.
-   */
   uri: uri.ClusterUri;
-  /**
-   * loggedInUser is present if the user has logged in to the cluster at least once. This
-   * includes a situation in which the cert has expired. If the cluster was added to the app but the
-   * user is yet to log in, loggedInUser is not present.
-   */
   loggedInUser?: LoggedInUser;
-  /**
-   * Address of the proxy used to connect to this cluster. Always includes port number. Present only
-   * for root clusters.
-   *
-   * @example
-   * "teleport-14-ent.example.com:3090"
-   */
-  proxyHost: string;
 }
 
-/**
- * LoggedInUser describes loggedInUser field available on root clusters.
- *
- * loggedInUser is present if the user has logged in to the cluster at least once. This
- * includes a situation in which the cert has expired. If the cluster was added to the app but the
- * user is yet to log in, loggedInUser is not present.
- */
 export type LoggedInUser = apiCluster.LoggedInUser & {
   assumedRequests?: Record<string, AssumedRequest>;
-  /**
-   * acl is available only after the cluster details are fetched, as acl is not stored on disk.
-   */
-  acl?: apiCluster.ACL;
 };
 export type AuthProvider = apiAuthSettings.AuthProvider;
 export type AuthSettings = apiAuthSettings.AuthSettings;