Merge pull request #3973 from wkloucek/config-doc-descriptions

add more config doc descriptions

changelog/unreleased/fix-remove-unused-config-options.md

@@ -0,0 +1,12 @@
+Bugfix: Remove unused configuration options
+
+We've removed multiple unused configuration options:
+
+- `STORAGE_SYSTEM_DATAPROVIDER_INSECURE`, see also cs3org/reva#2993
+- `STORAGE_USERS_DATAPROVIDER_INSECURE`, see also cs3org/reva#2993
+- `STORAGE_SYSTEM_TEMP_FOLDER`, see also cs3org/reva#2993
+- `STORAGE_USERS_TEMP_FOLDER`, see also cs3org/reva#2993
+- `WEB_UI_CONFIG_VERSION`, see also owncloud/web#7130
+- `GATEWAY_COMMIT_SHARE_TO_STORAGE_REF`, see also cs3org/reva#3017
+
+https://github.com/owncloud/ocis/pull/3973

docs/services/graph-explorer/_index.md

@@ -8,4 +8,11 @@ geekdocFilePath: _index.md
 geekdocCollapseSection: true
 ---
 
+## Abstract
+
+
 This service embeds [Graph-Explorer](https://github.com/owncloud/ocis/tree/master/graph-explorer) to provide a UI for ownCloud Infinite Scale.
+
+## Table of Contents
+
+{{< toc-tree >}}

docs/services/graph/_index.md

@@ -8,6 +8,10 @@ geekdocFilePath: _index.md
 geekdocCollapseSection: true
 ---
 
+## Abstract
+
 This service provides a simple graph world API which can be used by clients or other extensions.
 
+## Table of Contents
+
 {{< toc-tree >}}

docs/services/idp/_index.md

@@ -7,4 +7,10 @@ geekdocFilePath: _index.md
 geekdocCollapseSection: true
 ---
 
+## Abstract
+
 This service provides an OpenID Connect provider which is the default way to authenticate in oCIS.
+
+## Table of Contents
+
+{{< toc-tree >}}

docs/services/ocdav/_index.md

@@ -9,6 +9,7 @@ geekdocCollapseSection: true
 ---
 
 ## Abstract
+This service provides the WebDAV API which is required by ownCloud clients. Previews (thumbnails) are provided by the [WebDAV service]({{ ../../webdav }}).
 
 
 ## Table of Contents

docs/services/ocs/_index.md

@@ -8,4 +8,10 @@ geekdocFilePath: _index.md
 geekdocCollapseSection: true
 ---
 
+## Abstract
+
 This service provides the OCS API which is required by some ownCloud clients.
+
+## Table of Contents
+
+{{< toc-tree >}}

docs/services/proxy/_index.md

@@ -7,4 +7,10 @@ geekdocFilePath: _index.md
 geekdocCollapseSection: true
 ---
 
-This service provides a proxy service that routes requests to the correct extensions.
+## Abstract
+
+The proxy service acts as an API Gateway and routes requests to the correct target service. It also provides standard proxy services.
+
+## Table of Contents
+
+{{< toc-tree >}}

docs/services/search/_index.md

@@ -7,4 +7,10 @@ geekdocFilePath: _index.md
 geekdocCollapseSection: true
 ---
 
+## Abstract
+
 This service provides search functionality.
+
+## Table of Contents
+
+{{< toc-tree >}}

docs/services/settings/_index.md

@@ -45,3 +45,7 @@ The forms are generated from the registered *settings bundles*.
 if it's available. The SDK uses sensible defaults when ocis-settings is not part of the setup.
 
 For compatibility with ownCloud 10, a migration of ownCloud 10 settings into the storage of ocis-settings will be available.
+
+## Table of Contents
+
+{{< toc-tree >}}

docs/services/sharing/_index.md

@@ -7,4 +7,10 @@ geekdocFilePath: _index.md
 geekdocCollapseSection: true
 ---
 
+## Abstract
+
 This service provides sharing functionality.
+
+## Table of Contents
+
+{{< toc-tree >}}

docs/services/store/_index.md

@@ -8,4 +8,11 @@ geekdocFilePath: _index.md
 geekdocCollapseSection: true
 ---
 
+## Abstract
+
 This service provides ...
+
+
+## Table of Contents
+
+{{< toc-tree >}}

docs/services/thumbnails/_index.md

@@ -8,4 +8,11 @@ geekdocFilePath: _index.md
 geekdocCollapseSection: true
 ---
 
-This service provides an ocis extensions which generates thumbnails for image files.
+## Abstract
+
+The thumbnail service generates thumbnails for image files.
+
+
+## Table of Contents
+
+{{< toc-tree >}}

docs/services/web/_index.md

@@ -8,4 +8,11 @@ geekdocFilePath: _index.md
 geekdocCollapseSection: true
 ---
 
-This service embeds [ownCloud Web](https://github.com/owncloud/web) to provide a UI for ownCloud Infinite Scale.
+## Abstract
+
+The web service embeds [ownCloud Web](https://github.com/owncloud/web) to provide a UI for ownCloud Infinite Scale.
+
+
+## Table of Contents
+
+{{< toc-tree >}}

docs/services/webdav/_index.md

@@ -1,5 +1,5 @@
 ---
-title: WebDaV
+title: WebDAV
 date: 2018-05-02T00:00:00+00:00
 weight: 20
 geekdocRepo: https://github.com/owncloud/ocis
@@ -8,4 +8,10 @@ geekdocFilePath: _index.md
 geekdocCollapseSection: true
 ---
 
-This service provides the WebDAV API which is required by some ownCloud clients.
+## Abstract
+
+This service provides preview (thumbnails) endpoints on the WebDAV API and therefore extends the main WebDAV API provided by the [oCDAV service]({{ ../../ocdav }}).
+
+## Table of Contents
+
+{{< toc-tree >}}

ocis-pkg/config/config.go

@@ -61,14 +61,14 @@ type Config struct {
 
 	Mode    Mode // DEPRECATED
 	File    string
-	OcisURL string `yaml:"ocis_url"`
+	OcisURL string `yaml:"ocis_url" desc:"URL, where oCIS is reachable for users."`
 
 	Registry          string               `yaml:"registry"`
 	TokenManager      *shared.TokenManager `yaml:"token_manager"`
 	MachineAuthAPIKey string               `yaml:"machine_auth_api_key" env:"OCIS_MACHINE_AUTH_API_KEY" desc:"Machine auth API key used for accessing the 'auth-machine' service to impersonate users."`
 	TransferSecret    string               `yaml:"transfer_secret" env:"STORAGE_TRANSFER_SECRET"`
-	SystemUserID      string               `yaml:"system_user_id" env:"OCIS_SYSTEM_USER_ID"`
-	SystemUserAPIKey  string               `yaml:"system_user_api_key" env:"OCIS_SYSTEM_USER_API_KEY"`
+	SystemUserID      string               `yaml:"system_user_id" env:"OCIS_SYSTEM_USER_ID" desc:"ID of the oCIS storage-system system user. Admins need to set the ID for the storage-system system user in this config option which is then used to reference the user. Any reasonable long string is possible, preferably this would be an UUIDv4 format."`
+	SystemUserAPIKey  string               `yaml:"system_user_api_key" env:"OCIS_SYSTEM_USER_API_KEY" desc:"API key for the storage-system system user."`
 	AdminUserID       string               `yaml:"admin_user_id" env:"OCIS_ADMIN_USER_ID" desc:"ID of a user, that should receive admin privileges."`
 	Runtime           Runtime              `yaml:"runtime"`
 

ocis-pkg/shared/shared_types.go

@@ -39,12 +39,12 @@ type Reva struct {
 type Commons struct {
 	Log               *Log          `yaml:"log"`
 	Tracing           *Tracing      `yaml:"tracing"`
-	OcisURL           string        `yaml:"ocis_url" env:"OCIS_URL"`
+	OcisURL           string        `yaml:"ocis_url" env:"OCIS_URL" desc:"URL, where oCIS is reachable for users."`
 	TokenManager      *TokenManager `yaml:"token_manager"`
 	Reva              *Reva         `yaml:"reva"`
 	MachineAuthAPIKey string        `yaml:"machine_auth_api_key" env:"OCIS_MACHINE_AUTH_API_KEY" desc:"Machine auth API key used for accessing the 'auth-machine' service to impersonate users."`
 	TransferSecret    string        `yaml:"transfer_secret,omitempty" env:"REVA_TRANSFER_SECRET"`
-	SystemUserID      string        `yaml:"system_user_id" env:"OCIS_SYSTEM_USER_ID"`
+	SystemUserID      string        `yaml:"system_user_id" env:"OCIS_SYSTEM_USER_ID" desc:"ID of the oCIS storage-system system user. Admins need to set the ID for the storage-system system user in this config option which is then used to reference the user. Any reasonable long string is possible, preferably this would be an UUIDv4 format."`
 	SystemUserAPIKey  string        `yaml:"system_user_api_key" env:"SYSTEM_USER_API_KEY"`
 	AdminUserID       string        `yaml:"admin_user_id" env:"OCIS_ADMIN_USER_ID" desc:"ID of a user, that should receive admin privileges."`
 }

ocis/pkg/init/init.go

@@ -31,10 +31,6 @@ type InsecureProxyExtension struct {
 	InsecureBackends bool `yaml:"insecure_backends"`
 }
 
-type DataProviderInsecureSettings struct {
-	DataProviderInsecure bool `yaml:"data_provider_insecure"`
-}
-
 type LdapSettings struct {
 	BindPassword string `yaml:"bind_password"`
 }
@@ -114,8 +110,6 @@ type OcisConfig struct {
 	AuthBearer        AuthbearerExtension `yaml:"auth_bearer"`
 	Users             UsersAndGroupsExtension
 	Groups            UsersAndGroupsExtension
-	StorageSystem     DataProviderInsecureSettings `yaml:"storage_system"`
-	StorageUsers      DataProviderInsecureSettings `yaml:"storage_users"`
 	Ocdav             InsecureExtension
 	Thumbnails        ThumbnailExtension
 }
@@ -289,12 +283,6 @@ func CreateConfig(insecure, forceOverwrite bool, configPath, adminPassword strin
 		cfg.Proxy = InsecureProxyExtension{
 			InsecureBackends: true,
 		}
-		cfg.StorageSystem = DataProviderInsecureSettings{
-			DataProviderInsecure: true,
-		}
-		cfg.StorageUsers = DataProviderInsecureSettings{
-			DataProviderInsecure: true,
-		}
 
 		cfg.Thumbnails.Thumbnail.WebdavAllowInsecure = true
 		cfg.Thumbnails.Thumbnail.Cs3AllowInsecure = true

services/app-provider/pkg/config/config.go

@@ -52,7 +52,7 @@ type Debug struct {
 }
 
 type GRPCConfig struct {
-	Addr      string `yaml:"addr" env:"APP_PROVIDER_GRPC_ADDR" desc:"The address of the grpc service."`
+	Addr      string `yaml:"addr" env:"APP_PROVIDER_GRPC_ADDR" desc:"The bind address of the GRPC service."`
 	Namespace string `yaml:"-"`
 	Protocol  string `yaml:"protocol" env:"APP_PROVIDER_GRPC_PROTOCOL" desc:"The transport protocol of the grpc service."`
 }

services/app-registry/pkg/config/config.go

@@ -50,7 +50,7 @@ type Debug struct {
 }
 
 type GRPCConfig struct {
-	Addr      string `yaml:"addr" env:"APP_REGISTRY_GRPC_ADDR" desc:"The address of the grpc service."`
+	Addr      string `yaml:"addr" env:"APP_REGISTRY_GRPC_ADDR" desc:"The bind address of the GRPC service."`
 	Namespace string `yaml:"-"`
 	Protocol  string `yaml:"protocol" env:"APP_REGISTRY_GRPC_PROTOCOL" desc:"The transport protocol of the grpc service."`
 }

services/auth-basic/pkg/config/config.go

@@ -18,7 +18,7 @@ type Config struct {
 	TokenManager *TokenManager `yaml:"token_manager"`
 	Reva         *Reva         `yaml:"reva"`
 
-	SkipUserGroupsInToken bool          `yaml:"skip_user_groups_in_token" env:"AUTH_BASIC_SKIP_USER_GROUPS_IN_TOKEN" desc:"Disables the encoding of the user's groupmember ships in the reva access token. To reduces token size, especially when users are members of a large number of groups."`
+	SkipUserGroupsInToken bool          `yaml:"skip_user_groups_in_token" env:"AUTH_BASIC_SKIP_USER_GROUPS_IN_TOKEN" desc:"Disables the encoding of the user's group memberships in the reva access token. This reduces the token size, especially when users are members of a large number of groups."`
 	AuthProvider          string        `yaml:"auth_provider" env:"AUTH_BASIC_AUTH_PROVIDER" desc:"The auth provider which should be used by the service (e.g. 'ldap')."`
 	AuthProviders         AuthProviders `yaml:"auth_providers"`
 
@@ -51,7 +51,7 @@ type Debug struct {
 }
 
 type GRPCConfig struct {
-	Addr      string `yaml:"addr" env:"AUTH_BASIC_GRPC_ADDR" desc:"The address of the grpc service."`
+	Addr      string `yaml:"addr" env:"AUTH_BASIC_GRPC_ADDR" desc:"The bind address of the GRPC service."`
 	Namespace string `yaml:"-"`
 	Protocol  string `yaml:"protocol" env:"AUTH_BASIC_GRPC_PROTOCOL" desc:"The transport protocol of the grpc service."`
 }

services/auth-bearer/pkg/config/config.go

@@ -18,7 +18,7 @@ type Config struct {
 	TokenManager *TokenManager `yaml:"token_manager"`
 	Reva         *Reva         `yaml:"reva"`
 
-	SkipUserGroupsInToken bool `yaml:"skip_user_groups_in_token" env:"AUTH_BEARER_SKIP_USER_GROUPS_IN_TOKEN" desc:"Skip storing all groups of a user in the jwt token."`
+	SkipUserGroupsInToken bool `yaml:"skip_user_groups_in_token" env:"AUTH_BEARER_SKIP_USER_GROUPS_IN_TOKEN" desc:"Disables the encoding of the user's group memberships in the reva access token. This reduces the token size, especially when users are members of a large number of groups."`
 
 	OIDC OIDC `yaml:"oidc"`
 
@@ -51,7 +51,7 @@ type Debug struct {
 }
 
 type GRPCConfig struct {
-	Addr      string `yaml:"addr" env:"AUTH_BEARER_GRPC_ADDR" desc:"The address of the grpc service."`
+	Addr      string `yaml:"addr" env:"AUTH_BEARER_GRPC_ADDR" desc:"The bind address of the GRPC service."`
 	Namespace string `yaml:"-"`
 	Protocol  string `yaml:"protocol" env:"AUTH_BEARER_GRPC_PROTOCOL" desc:"The transport protocol of the grpc service."`
 }

services/auth-machine/pkg/config/config.go

@@ -18,7 +18,7 @@ type Config struct {
 	TokenManager *TokenManager `yaml:"token_manager"`
 	Reva         *Reva         `yaml:"reva"`
 
-	SkipUserGroupsInToken bool `yaml:"skip_user_groups_in_token" env:"AUTH_MACHINE_SKIP_USER_GROUPS_IN_TOKEN" desc:"Skip storing all groups of a user in the jwt token."`
+	SkipUserGroupsInToken bool `yaml:"skip_user_groups_in_token" env:"AUTH_MACHINE_SKIP_USER_GROUPS_IN_TOKEN" desc:"Disables the encoding of the user's group memberships in the reva access token. This reduces the token size, especially when users are members of a large number of groups."`
 
 	MachineAuthAPIKey string `yaml:"machine_auth_api_key" env:"OCIS_MACHINE_AUTH_API_KEY;AUTH_MACHINE_API_KEY" desc:"Machine auth API key used for validating requests from other services when impersonating users."`
 
@@ -51,7 +51,7 @@ type Debug struct {
 }
 
 type GRPCConfig struct {
-	Addr      string `yaml:"addr" env:"AUTH_MACHINE_GRPC_ADDR" desc:"The address of the grpc service."`
+	Addr      string `yaml:"addr" env:"AUTH_MACHINE_GRPC_ADDR" desc:"The bind address of the GRPC service."`
 	Namespace string `yaml:"-"`
 	Protocol  string `yaml:"protocol" env:"AUTH_MACHINE_GRPC_PROTOCOL" desc:"The transport protocol of the grpc service."`
 }

services/frontend/pkg/config/config.go

@@ -17,13 +17,13 @@ type Config struct {
 
 	// JWTSecret used to verify reva access token
 
-	TransferSecret string `yaml:"transfer_secret" env:"STORAGE_TRANSFER_SECRET"`
+	TransferSecret string `yaml:"transfer_secret" env:"STORAGE_TRANSFER_SECRET" desc:"Transfer secret for signing file up- and download requests."`
 
 	TokenManager      *TokenManager `yaml:"token_manager"`
 	Reva              *Reva         `yaml:"reva"`
-	MachineAuthAPIKey string        `yaml:"machine_auth_api_key" env:"OCIS_MACHINE_AUTH_API_KEY;FRONTEND_MACHINE_AUTH_API_KEY" desc:"Machine auth API key used for accessing the 'auth-machine' service."`
+	MachineAuthAPIKey string        `yaml:"machine_auth_api_key" env:"OCIS_MACHINE_AUTH_API_KEY;FRONTEND_MACHINE_AUTH_API_KEY" desc:"Machine auth API key used for accessing the 'auth-machine' service to impersonate users."`
 
-	SkipUserGroupsInToken bool `yaml:"skip_user_groups_in_token" env:"FRONTEND_SKIP_USER_GROUPS_IN_TOKEN" desc:"Disables the encoding of the user's group memberships in the reva access token. This reduces token size, especially when users are members of a large number of groups."`
+	SkipUserGroupsInToken bool `yaml:"skip_user_groups_in_token" env:"FRONTEND_SKIP_USER_GROUPS_IN_TOKEN" desc:"Disables the loading of user's group memberships from the reva access token."`
 
 	EnableFavorites          bool   `yaml:"enable_favorites" env:"FRONTEND_ENABLE_FAVORITES" desc:"Enables the support for favorites in the frontend."`
 	EnableProjectSpaces      bool   `yaml:"enable_project_spaces" env:"FRONTEND_ENABLE_PROJECT_SPACES" desc:"Indicates to clients that project spaces are supposed to be made available."`
@@ -72,7 +72,7 @@ type Debug struct {
 }
 
 type HTTPConfig struct {
-	Addr      string `yaml:"addr" env:"FRONTEND_HTTP_ADDR" desc:"The address of the http service."`
+	Addr      string `yaml:"addr" env:"FRONTEND_HTTP_ADDR" desc:"The bind address of the HTTP service."`
 	Namespace string `yaml:"-"`
 	Protocol  string `yaml:"protocol" env:"FRONTEND_HTTP_PROTOCOL" desc:"The transport protocol of the http service."`
 	Prefix    string `yaml:"prefix" env:"FRONTEND_HTTP_PREFIX" desc:"The Path prefix where the frontend can be accessed (defaults to /)."`

services/gateway/pkg/config/config.go

@@ -19,15 +19,14 @@ type Config struct {
 	TokenManager *TokenManager `yaml:"token_manager"`
 	Reva         *Reva         `yaml:"reva"`
 
-	SkipUserGroupsInToken bool `yaml:"skip_user_groups_in_token" env:"GATEWAY_SKIP_USER_GROUPS_IN_TOKEN" desc:"Disables the encoding of the user's groupmember ships in the reva access token. To reduces token size, especially when users are members of a large number of groups."`
+	SkipUserGroupsInToken bool `yaml:"skip_user_groups_in_token" env:"GATEWAY_SKIP_USER_GROUPS_IN_TOKEN" desc:"Disables the loading of user's group memberships from the reva access token."`
 
-	CommitShareToStorageGrant  bool   `yaml:"commit_share_to_storage_grant" env:"GATEWAY_COMMIT_SHARE_TO_STORAGE_GRANT" desc:"Commit shares to storage grants (default: true)."`
-	CommitShareToStorageRef    bool   `yaml:"commit_share_to_storage_ref" env:"GATEWAY_COMMIT_SHARE_TO_STORAGE_REF" desc:"Commit shares to storage (default: true)"`
-	ShareFolder                string `yaml:"share_folder_name" env:"GATEWAY_SHARE_FOLDER_NAME" desc:"Name of the gateway share folder"`
-	DisableHomeCreationOnLogin bool   `yaml:"disable_home_creation_on_login" env:"GATEWAY_DISABLE_HOME_CREATION_ON_LOGIN" desc:"Disable creation of the homespace on login"`
+	CommitShareToStorageGrant  bool   `yaml:"commit_share_to_storage_grant" env:"GATEWAY_COMMIT_SHARE_TO_STORAGE_GRANT" desc:"Commit shares to storage grants. This grants access to shared resources for the share receiver directly on the storage."`
+	ShareFolder                string `yaml:"share_folder_name" env:"GATEWAY_SHARE_FOLDER_NAME" desc:"Name of the share folder in users' home space."`
+	DisableHomeCreationOnLogin bool   `yaml:"disable_home_creation_on_login" env:"GATEWAY_DISABLE_HOME_CREATION_ON_LOGIN" desc:"Disable creation of the home space on login."`
 	TransferSecret             string `yaml:"transfer_secret" env:"STORAGE_TRANSFER_SECRET" desc:"The storage transfer secret"` // TODO: how to name the env
 	TransferExpires            int    `yaml:"transfer_expires" env:"GATEWAY_TRANSFER_EXPIRES" desc:"Expiry for the gateway tokens"`
-	EtagCacheTTL               int    `yaml:"etag_cache_ttl" env:"GATEWAY_ETAG_CACHE_TTL" desc:"Max TTL for the gatways ETAG cache."`
+	EtagCacheTTL               int    `yaml:"etag_cache_ttl" env:"GATEWAY_ETAG_CACHE_TTL" desc:"Max TTL in seconds for the gateway's ETAG cache."`
 
 	FrontendPublicURL string `yaml:"frontend_public_url" env:"OCIS_URL;GATEWAY_FRONTEND_PUBLIC_URL" desc:"The public facing url of the ocis frontend."`
 
@@ -74,7 +73,7 @@ type Debug struct {
 }
 
 type GRPCConfig struct {
-	Addr      string `yaml:"addr" env:"GATEWAY_GRPC_ADDR" desc:"The address of the grpc service."`
+	Addr      string `yaml:"addr" env:"GATEWAY_GRPC_ADDR" desc:"The bind address of the GRPC service."`
 	Namespace string `yaml:"-"`
 	Protocol  string `yaml:"protocol" env:"GATEWAY_GRPC_PROTOCOL" desc:"The transport protocol of the grpc service."`
 }

services/gateway/pkg/config/defaults/defaultconfig.go

@@ -32,7 +32,6 @@ func DefaultConfig() *config.Config {
 		},
 
 		CommitShareToStorageGrant:  true,
-		CommitShareToStorageRef:    true,
 		ShareFolder:                "Shares",
 		DisableHomeCreationOnLogin: true,
 		TransferExpires:            24 * 60 * 60,

services/gateway/pkg/revaconfig/config.go

@@ -45,7 +45,6 @@ func GatewayConfigFromStruct(cfg *config.Config, logger log.Logger) map[string]i
 					"publicshareprovidersvc":        cfg.SharingEndpoint,
 					"ocmshareprovidersvc":           cfg.SharingEndpoint,
 					"commit_share_to_storage_grant": cfg.CommitShareToStorageGrant,
-					"commit_share_to_storage_ref":   cfg.CommitShareToStorageRef,
 					"share_folder":                  cfg.ShareFolder, // ShareFolder is the location where to create shares in the recipient's storage provider.
 					// other
 					"disable_home_creation_on_login": cfg.DisableHomeCreationOnLogin,

services/graph-explorer/pkg/config/http.go

@@ -2,8 +2,8 @@ package config
 
 // HTTP defines the available http configuration.
 type HTTP struct {
-	Addr      string `yaml:"addr" env:"GRAPH_EXPLORER_HTTP_ADDR" desc:"The HTTP service address."`
-	Root      string `yaml:"root" env:"GRAPH_EXPLORER_HTTP_ROOT" desc:"The HTTP service root path."`
+	Addr      string `yaml:"addr" env:"GRAPH_EXPLORER_HTTP_ADDR" desc:"The bind address of the HTTP service."`
+	Root      string `yaml:"root" env:"GRAPH_EXPLORER_HTTP_ROOT" desc:"Subdirectory that serves as the root for this HTTP service."`
 	Namespace string `yaml:"-"`
 }
 

services/graph/pkg/config/http.go

@@ -2,7 +2,7 @@ package config
 
 // HTTP defines the available http configuration.
 type HTTP struct {
-	Addr      string `yaml:"addr" env:"GRAPH_HTTP_ADDR"`
+	Addr      string `yaml:"addr" env:"GRAPH_HTTP_ADDR" desc:"The bind address of the HTTP service."`
 	Namespace string `yaml:"-"`
-	Root      string `yaml:"root" env:"GRAPH_HTTP_ROOT"`
+	Root      string `yaml:"root" env:"GRAPH_HTTP_ROOT" desc:"Subdirectory that serves as the root for this HTTP service."`
 }