Improve error and copy in params/models

2024-06-01 18:39:57 +12:00 · 2023-08-22 20:11:33 +00:00 · 2023-08-22 20:11:33 +00:00 · 07a7a710ee
parent caf6bcae95
commit 07a7a710ee
17 changed files with 62 additions and 62 deletions
--- a/app/config/services.php
+++ b/app/config/services.php
@ -189,7 +189,7 @@ return [
    'proxy' => [
        'key' => 'proxy',
        'name' => 'Proxy',
-        'subtitle' => 'The Proxy Service allows you configure actions for your domains beyond DNS configuration.',
+        'subtitle' => 'The Proxy Service allows you to configure actions for your domains beyond DNS configuration.',
        'description' => '/docs/services/proxy.md',
        'controller' => 'api/proxy.php',
        'sdk' => true,
@ -241,7 +241,7 @@ return [
    'migrations' => [
        'key' => 'migrations',
        'name' => 'Migrations',
-        'subtitle' => 'The Migrations service allows you to migrate third-party data to your Appwrite server.',
+        'subtitle' => 'The Migrations service allows you to migrate third-party data to your Appwrite project.',
        'description' => '/docs/services/migrations.md',
        'controller' => 'api/migrations.php',
        'sdk' => true,
--- a/app/config/variables.php
+++ b/app/config/variables.php
@ -116,7 +116,7 @@ return [
            ],
            [
                'name' => '_APP_CONSOLE_ROOT_SESSION',
-                'description' => 'Domain policy for the Appwrite console session cookie. By default, set to \'disabled\', meaning the session cookie will be set to the domain of the Appwrite console (e.g. cloud.appwrite.io). When set to \'enabled\', the session cookie will be set to the registerable domain of the Appwrite server (e.g. appwrite.io).',
+                'description' => 'Domain policy for the Appwrite console session cookie. By default, set to \'disabled\', meaning the session cookie will be set to the domain of the Appwrite console, for example, "cloud.appwrite.io". When set to \'enabled\', the session cookie will be set to the registerable domain of the Appwrite server, for example, "appwrite.io".',
                'introduction' => '',
                'default' => 'disabled',
                'required' => false,
@ -161,7 +161,7 @@ return [
            ],
            [
                'name' => '_APP_USAGE_STATS',
-                'description' => 'This variable allows you to disable the collection and displaying of usage stats. This value is set to \'enabled\' by default, to disable the usage stats set the value to \'disabled\'. When disabled, it\'s recommended to turn off the Worker Usage container for better resource usage.',
+                'description' => 'This variable allows you to disable the collection and displaying of usage stats. This value is set to \'enabled\' by default, to disable the usage stats set the value to \'disabled\'. When disabled, it\'s recommended to turn off the Worker Usage container to reduce resource usage.',
                'introduction' => '0.7.0',
                'default' => 'enabled',
                'required' => false,
@ -170,7 +170,7 @@ return [
            ],
            [
                'name' => '_APP_LOGGING_PROVIDER',
-                'description' => 'This variable allows you to enable logging errors to 3rd party providers. This value is empty by default, to enable the logger set the value to one of \'sentry\', \'raygun\', \'appSignal\', \'logOwl\'',
+                'description' => 'This variable allows you to enable logging errors to 3rd party providers. This value is empty by default, set the value to one of \'sentry\', \'raygun\', \'appSignal\', \'logOwl\' to enable the logger.',
                'introduction' => '0.12.0',
                'default' => '',
                'required' => false,
@ -823,7 +823,7 @@ return [
            ],
            [
                'name' => '_APP_FUNCTIONS_RUNTIMES_NETWORK',
-                'description' => 'The docker network used for communication between the executor and runtimes. Change this if you have altered the default network names.',
+                'description' => 'The docker network used for communication between the executor and runtimes.',
                'introduction' => '1.2.0',
                'default' => 'runtimes',
                'required' => false,
@ -865,7 +865,7 @@ return [
        'variables' => [
            [
                'name' => '_APP_VCS_GITHUB_APP_NAME',
-                'description' => 'Name of your GitHub app. You can find it in URL of your GitHub application.',
+                'description' => 'Name of your GitHub app. This value should be set to your GitHub application\'s URL.',
                'introduction' => '1.4.0',
                'default' => '',
                'required' => false,
--- a/app/controllers/api/account.php
+++ b/app/controllers/api/account.php
@ -453,7 +453,7 @@ App::get('/v1/account/sessions/oauth2/callback/:provider/:projectId')
    ->label('docs', false)
    ->param('projectId', '', new Text(1024), 'Project ID.')
    ->param('provider', '', new WhiteList(\array_keys(Config::getParam('providers')), true), 'OAuth2 provider.')
-    ->param('code', '', new Text(2048, 0), 'OAuth2 code.', true)
+    ->param('code', '', new Text(2048, 0), 'OAuth2 code. This is a temporary code that the will be later exchanged for an access token.', true)
    ->param('state', '', new Text(2048), 'Login state params.', true)
    ->param('error', '', new Text(2048, 0), 'Error code returned from the OAuth2 provider.', true)
    ->param('error_description', '', new Text(2048, 0), 'Human-readable text providing additional information about the error returned from the OAuth2 provider.', true)
@ -486,7 +486,7 @@ App::post('/v1/account/sessions/oauth2/callback/:provider/:projectId')
    ->label('docs', false)
    ->param('projectId', '', new Text(1024), 'Project ID.')
    ->param('provider', '', new WhiteList(\array_keys(Config::getParam('providers')), true), 'OAuth2 provider.')
-    ->param('code', '', new Text(2048, 0), 'OAuth2 code.', true)
+    ->param('code', '', new Text(2048, 0), 'OAuth2 code. This is a temporary code that the will be later exchanged for an access token.', true)
    ->param('state', '', new Text(2048), 'Login state params.', true)
    ->param('error', '', new Text(2048, 0), 'Error code returned from the OAuth2 provider.', true)
    ->param('error_description', '', new Text(2048, 0), 'Human-readable text providing additional information about the error returned from the OAuth2 provider.', true)
@ -525,7 +525,7 @@ App::get('/v1/account/sessions/oauth2/:provider/redirect')
    ->label('usage.metric', 'sessions.{scope}.requests.create')
    ->label('usage.params', ['provider:{request.provider}'])
    ->param('provider', '', new WhiteList(\array_keys(Config::getParam('providers')), true), 'OAuth2 provider.')
-    ->param('code', '', new Text(2048, 0), 'OAuth2 code.', true)
+    ->param('code', '', new Text(2048, 0), 'OAuth2 code. This is a temporary code that the will be later exchanged for an access token.', true)
    ->param('state', '', new Text(2048), 'OAuth2 state params.', true)
    ->param('error', '', new Text(2048, 0), 'Error code returned from the OAuth2 provider.', true)
    ->param('error_description', '', new Text(2048, 0), 'Human-readable text providing additional information about the error returned from the OAuth2 provider.', true)
--- a/app/controllers/api/console.php
+++ b/app/controllers/api/console.php
@ -59,7 +59,7 @@ App::post('/v1/console/assistant')
    ->label('sdk.response.type', Response::CONTENT_TYPE_TEXT)
    ->label('abuse-limit', 15)
    ->label('abuse-key', 'userId:{userId}')
-    ->param('prompt', '', new Text(2000), 'Prompt')
+    ->param('prompt', '', new Text(2000), 'Prompt. A string containing questions asked to the AI assistant.')
    ->inject('response')
    ->action(function (string $prompt, Response $response) {
        $ch = curl_init('http://appwrite-assistant:3003/');
--- a/app/controllers/api/databases.php
+++ b/app/controllers/api/databases.php
@ -386,7 +386,7 @@ App::post('/v1/databases')
    ->label('sdk.response.model', Response::MODEL_DATABASE) // Model for database needs to be created
    ->param('databaseId', '', new CustomId(), 'Unique Id. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can\'t start with a special char. Max length is 36 chars.')
    ->param('name', '', new Text(128), 'Database name. Max length: 128 chars.')
-    ->param('enabled', true, new Boolean(), 'Is database enabled?', true)
+    ->param('enabled', true, new Boolean(), 'Is the database enabled? When set to \'disabled\', users cannot access the database but Server SDKs with an API key can still read and write to the database. No data is lost when this is toggled.', true)
    ->inject('response')
    ->inject('dbForProject')
    ->inject('events')
@ -621,7 +621,7 @@ App::put('/v1/databases/:databaseId')
    ->label('sdk.response.model', Response::MODEL_DATABASE)
    ->param('databaseId', '', new UID(), 'Database ID.')
    ->param('name', null, new Text(128), 'Database name. Max length: 128 chars.')
-    ->param('enabled', true, new Boolean(), 'Is database enabled?', true)
+    ->param('enabled', true, new Boolean(), 'Is database enabled? When set to \'disabled\', users cannot access the database but Server SDKs with an API key can still read and write to the database. No data is lost when this is toggled.', true)
    ->inject('response')
    ->inject('dbForProject')
    ->inject('events')
@ -716,7 +716,7 @@ App::post('/v1/databases/:databaseId/collections')
    ->param('name', '', new Text(128), 'Collection name. Max length: 128 chars.')
    ->param('permissions', null, new Permissions(APP_LIMIT_ARRAY_PARAMS_SIZE), 'An array of permissions strings. By default, no user is granted with any permissions. [Learn more about permissions](/docs/permissions).', true)
    ->param('documentSecurity', false, new Boolean(true), 'Enables configuring permissions for individual documents. A user needs one of document or collection level permissions to access a document. [Learn more about permissions](/docs/permissions).', true)
-    ->param('enabled', true, new Boolean(), 'Is collection enabled?', true)
+    ->param('enabled', true, new Boolean(), 'Is collection enabled? When set to \'disabled\', users cannot access the collection but Server SDKs with and API key can still read and write to the collection. No data is lost when this is toggled.', true)
    ->inject('response')
    ->inject('dbForProject')
    ->inject('mode')
@ -975,7 +975,7 @@ App::put('/v1/databases/:databaseId/collections/:collectionId')
    ->param('name', null, new Text(128), 'Collection name. Max length: 128 chars.')
    ->param('permissions', null, new Permissions(APP_LIMIT_ARRAY_PARAMS_SIZE), 'An array of permission strings. By default, the current permissions are inherited. [Learn more about permissions](/docs/permissions).', true)
    ->param('documentSecurity', false, new Boolean(true), 'Enables configuring permissions for individual documents. A user needs one of document or collection level permissions to access a document. [Learn more about permissions](/docs/permissions).', true)
-    ->param('enabled', true, new Boolean(), 'Is collection enabled?', true)
+    ->param('enabled', true, new Boolean(), 'Is collection enabled? When set to \'disabled\', users cannot access the collection but Server SDKs with and API key can still read and write to the collection. No data is lost when this is toggled.', true)
    ->inject('response')
    ->inject('dbForProject')
    ->inject('mode')
--- a/app/controllers/api/functions.php
+++ b/app/controllers/api/functions.php
@ -135,23 +135,23 @@ App::post('/v1/functions')
    ->param('functionId', '', new CustomId(), 'Function ID. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can\'t start with a special char. Max length is 36 chars.')
    ->param('name', '', new Text(128), 'Function name. Max length: 128 chars.')
    ->param('runtime', '', new WhiteList(array_keys(Config::getParam('runtimes')), true), 'Execution runtime.')
-    ->param('execute', [], new Roles(APP_LIMIT_ARRAY_PARAMS_SIZE), 'An array of strings with execution roles. By default no user is granted with any execute permissions. [learn more about permissions](https://appwrite.io/docs/permissions). Maximum of ' . APP_LIMIT_ARRAY_PARAMS_SIZE . ' roles are allowed, each 64 characters long.', true)
+    ->param('execute', [], new Roles(APP_LIMIT_ARRAY_PARAMS_SIZE), 'An array of role strings with execution permissions. By default no user is granted with any execute permissions. [learn more about roles](https://appwrite.io/docs/permissions#permission-roles). Maximum of ' . APP_LIMIT_ARRAY_PARAMS_SIZE . ' roles are allowed, each 64 characters long.', true)
    ->param('events', [], new ArrayList(new ValidatorEvent(), APP_LIMIT_ARRAY_PARAMS_SIZE), 'Events list. Maximum of ' . APP_LIMIT_ARRAY_PARAMS_SIZE . ' events are allowed.', true)
    ->param('schedule', '', new Cron(), 'Schedule CRON syntax.', true)
    ->param('timeout', 15, new Range(1, (int) App::getEnv('_APP_FUNCTIONS_TIMEOUT', 900)), 'Function maximum execution time in seconds.', true)
-    ->param('enabled', true, new Boolean(), 'Is function enabled?', true)
-    ->param('logging', true, new Boolean(), 'Do executions get logged?', true)
-    ->param('entrypoint', '', new Text(1028), 'Entrypoint File.')
+    ->param('enabled', true, new Boolean(), 'Is function enabled? When set to \'disabled\', users cannot access the function but Server SDKs with and API key can still access the function. No data is lost when this is toggled.', true)
+    ->param('logging', true, new Boolean(), 'Whether executions will be logged. When set to false, executions will not be logged, but will reduce resource used by your Appwrite project.', true)
+    ->param('entrypoint', '', new Text(1028), 'Entrypoint File. This path is relative to the "providerRootDirectory".')
    ->param('commands', '', new Text(8192, 0), 'Build Commands.', true)
-    ->param('installationId', '', new Text(128, 0), 'Appwrite Installation ID for vcs deployment.', true)
-    ->param('providerRepositoryId', '', new Text(128, 0), 'Repository ID of the repo linked to the function', true)
-    ->param('providerBranch', '', new Text(128, 0), 'Production branch for the repo linked to the function', true)
-    ->param('providerSilentMode', false, new Boolean(), 'Is VCS connection in silent mode for the repo linked to the function?', true)
-    ->param('providerRootDirectory', '', new Text(128, 0), 'Path to function code in the linked repo', true)
-    ->param('templateRepository', '', new Text(128, 0), 'Repository name of the template', true)
-    ->param('templateOwner', '', new Text(128, 0), 'Owner name of the template', true)
-    ->param('templateRootDirectory', '', new Text(128, 0), 'Path to function code in the template repo', true)
-    ->param('templateBranch', '', new Text(128, 0), 'Branch of template repo with the code', true)
+    ->param('installationId', '', new Text(128, 0), 'Appwrite Installation ID for VCS (version control system) deployment.', true)
+    ->param('providerRepositoryId', '', new Text(128, 0), 'Repository ID of the repo linked to the function.', true)
+    ->param('providerBranch', '', new Text(128, 0), 'Production branch for the repo linked to the function.', true)
+    ->param('providerSilentMode', false, new Boolean(), 'Is the VCS connection in silent mode for the repo linked to the function? In silent mode, comments will not be made to pull requests.', true)
+    ->param('providerRootDirectory', '', new Text(128, 0), 'Path to function code in the linked repo.', true)
+    ->param('templateRepository', '', new Text(128, 0), 'Repository name of the template.', true)
+    ->param('templateOwner', '', new Text(128, 0), 'The name of the owner of the template.', true)
+    ->param('templateRootDirectory', '', new Text(128, 0), 'Path to function code in the template repo.', true)
+    ->param('templateBranch', '', new Text(128, 0), 'Production branch for the repo linked to the function template.', true)
    ->inject('request')
    ->inject('response')
    ->inject('dbForProject')
@ -659,19 +659,19 @@ App::put('/v1/functions/:functionId')
    ->param('functionId', '', new UID(), 'Function ID.')
    ->param('name', '', new Text(128), 'Function name. Max length: 128 chars.')
    ->param('runtime', '', new WhiteList(array_keys(Config::getParam('runtimes')), true), 'Execution runtime.')
-    ->param('execute', [], new Roles(APP_LIMIT_ARRAY_PARAMS_SIZE), 'An array of strings with execution roles. By default no user is granted with any execute permissions. [learn more about permissions](https://appwrite.io/docs/permissions). Maximum of ' . APP_LIMIT_ARRAY_PARAMS_SIZE . ' roles are allowed, each 64 characters long.', true)
+    ->param('execute', [], new Roles(APP_LIMIT_ARRAY_PARAMS_SIZE), 'An array of role strings with execution permissions. By default no user is granted with any execute permissions. [learn more about roles](https://appwrite.io/docs/permissions#permission-roles). Maximum of ' . APP_LIMIT_ARRAY_PARAMS_SIZE . ' roles are allowed, each 64 characters long.', true)
    ->param('events', [], new ArrayList(new ValidatorEvent(), APP_LIMIT_ARRAY_PARAMS_SIZE), 'Events list. Maximum of ' . APP_LIMIT_ARRAY_PARAMS_SIZE . ' events are allowed.', true)
    ->param('schedule', '', new Cron(), 'Schedule CRON syntax.', true)
    ->param('timeout', 15, new Range(1, (int) App::getEnv('_APP_FUNCTIONS_TIMEOUT', 900)), 'Maximum execution time in seconds.', true)
-    ->param('enabled', true, new Boolean(), 'Is function enabled?', true)
-    ->param('logging', true, new Boolean(), 'Do executions get logged?', true)
-    ->param('entrypoint', '', new Text(1028), 'Entrypoint File.')
+    ->param('enabled', true, new Boolean(), 'Is function enabled? When set to \'disabled\', users cannot access the function but Server SDKs with and API key can still access the function. No data is lost when this is toggled.', true)
+    ->param('logging', true, new Boolean(), 'Whether executions will be logged. When set to false, executions will not be logged, but will reduce resource used by your Appwrite project.', true)
+    ->param('entrypoint', '', new Text(1028), 'Entrypoint File. This path is relative to the "providerRootDirectory".')
    ->param('commands', '', new Text(8192, 0), 'Build Commands.', true)
    ->param('installationId', '', new Text(128, 0), 'Appwrite Installation ID for vcs deployment.', true)
    ->param('providerRepositoryId', '', new Text(128, 0), 'Repository ID of the repo linked to the function', true)
    ->param('providerBranch', '', new Text(128, 0), 'Production branch for the repo linked to the function', true)
-    ->param('providerSilentMode', false, new Boolean(), 'Is VCS connection in silent mode for the repo linked to the function?', true)
-    ->param('providerRootDirectory', '', new Text(128, 0), 'Path to function code in the linked repo', true)
+    ->param('providerSilentMode', false, new Boolean(), 'Is the VCS connection in silent mode for the repo linked to the function? In silent mode, comments will not be made to pull requests.', true)
+    ->param('providerRootDirectory', '', new Text(128, 0), 'Path to function code in the linked repo.', true)
    ->inject('request')
    ->inject('response')
    ->inject('dbForProject')
--- a/app/controllers/api/migrations.php
+++ b/app/controllers/api/migrations.php
@ -623,7 +623,7 @@ App::get('/v1/migrations/firebase/redirect')
    ->groups(['api', 'migrations'])
    ->label('scope', 'public')
    ->label('error', __DIR__ . '/../../views/general/error.phtml')
-    ->param('code', '', new Text(2048), 'OAuth2 code.', true)
+    ->param('code', '', new Text(2048), 'OAuth2 code. This is a temporary code that the will be later exchanged for an access token.', true)
    ->inject('user')
    ->inject('project')
    ->inject('request')
@ -857,12 +857,12 @@ App::get('/v1/migrations/supabase/report')
    ->label('sdk.response.type', Response::CONTENT_TYPE_JSON)
    ->label('sdk.response.model', Response::MODEL_MIGRATION_REPORT)
    ->param('resources', [], new ArrayList(new WhiteList(Supabase::getSupportedResources(), true)), 'List of resources to migrate')
-    ->param('endpoint', '', new URL(), 'Source\'s Supabase Endpoint')
-    ->param('apiKey', '', new Text(512), 'Source\'s API Key')
-    ->param('databaseHost', '', new Text(512), 'Source\'s Database Host')
-    ->param('username', '', new Text(512), 'Source\'s Database Username')
-    ->param('password', '', new Text(512), 'Source\'s Database Password')
-    ->param('port', 5432, new Integer(true), 'Source\'s Database Port', true)
+    ->param('endpoint', '', new URL(), 'Source\'s Supabase Endpoint.')
+    ->param('apiKey', '', new Text(512), 'Source\'s API Key.')
+    ->param('databaseHost', '', new Text(512), 'Source\'s Database Host.')
+    ->param('username', '', new Text(512), 'Source\'s Database Username.')
+    ->param('password', '', new Text(512), 'Source\'s Database Password.')
+    ->param('port', 5432, new Integer(true), 'Source\'s Database Port.', true)
    ->inject('response')
    ->inject('dbForProject')
    ->action(function (array $resources, string $endpoint, string $apiKey, string $databaseHost, string $username, string $password, int $port, Response $response) {
@ -888,14 +888,14 @@ App::get('/v1/migrations/nhost/report')
    ->label('sdk.response.code', Response::STATUS_CODE_OK)
    ->label('sdk.response.type', Response::CONTENT_TYPE_JSON)
    ->label('sdk.response.model', Response::MODEL_MIGRATION_REPORT)
-    ->param('resources', [], new ArrayList(new WhiteList(NHost::getSupportedResources())), 'List of resources to migrate')
-    ->param('subdomain', '', new Text(512), 'Source\'s Subdomain')
-    ->param('region', '', new Text(512), 'Source\'s Region')
-    ->param('adminSecret', '', new Text(512), 'Source\'s Admin Secret')
-    ->param('database', '', new Text(512), 'Source\'s Database Name')
-    ->param('username', '', new Text(512), 'Source\'s Database Username')
-    ->param('password', '', new Text(512), 'Source\'s Database Password')
-    ->param('port', 5432, new Integer(true), 'Source\'s Database Port', true)
+    ->param('resources', [], new ArrayList(new WhiteList(NHost::getSupportedResources())), 'List of resources to migrate.')
+    ->param('subdomain', '', new Text(512), 'Source\'s Subdomain.')
+    ->param('region', '', new Text(512), 'Source\'s Region.')
+    ->param('adminSecret', '', new Text(512), 'Source\'s Admin Secret.')
+    ->param('database', '', new Text(512), 'Source\'s Database Name.')
+    ->param('username', '', new Text(512), 'Source\'s Database Username.')
+    ->param('password', '', new Text(512), 'Source\'s Database Password.')
+    ->param('port', 5432, new Integer(true), 'Source\'s Database Port.', true)
    ->inject('response')
    ->action(function (array $resources, string $subdomain, string $region, string $adminSecret, string $database, string $username, string $password, int $port, Response $response) {
        try {
--- a/app/controllers/api/storage.php
+++ b/app/controllers/api/storage.php
@ -63,7 +63,7 @@ App::post('/v1/storage/buckets')
    ->param('name', '', new Text(128), 'Bucket name')
    ->param('permissions', null, new Permissions(APP_LIMIT_ARRAY_PARAMS_SIZE), 'An array of permission strings. By default, no user is granted with any permissions. [Learn more about permissions](/docs/permissions).', true)
    ->param('fileSecurity', false, new Boolean(true), 'Enables configuring permissions for individual file. A user needs one of file or bucket level permissions to access a file. [Learn more about permissions](/docs/permissions).', true)
-    ->param('enabled', true, new Boolean(true), 'Is bucket enabled?', true)
+    ->param('enabled', true, new Boolean(true), 'Is bucket enabled? When set to \'disabled\', users cannot access the files in this bucket but Server SDKs with and API key can still access the bucket. No files are lost when this is toggled.', true)
    ->param('maximumFileSize', (int) App::getEnv('_APP_STORAGE_LIMIT', 0), new Range(1, (int) App::getEnv('_APP_STORAGE_LIMIT', 0)), 'Maximum file size allowed in bytes. Maximum allowed value is ' . Storage::human(App::getEnv('_APP_STORAGE_LIMIT', 0), 0) . '.', true)
    ->param('allowedFileExtensions', [], new ArrayList(new Text(64), APP_LIMIT_ARRAY_PARAMS_SIZE), 'Allowed file extensions. Maximum of ' . APP_LIMIT_ARRAY_PARAMS_SIZE . ' extensions are allowed, each 64 characters long.', true)
    ->param('compression', COMPRESSION_TYPE_NONE, new WhiteList([COMPRESSION_TYPE_NONE, COMPRESSION_TYPE_GZIP, COMPRESSION_TYPE_ZSTD]), 'Compression algorithm choosen for compression. Can be one of ' . COMPRESSION_TYPE_NONE . ',  [' . COMPRESSION_TYPE_GZIP . '](https://en.wikipedia.org/wiki/Gzip), or [' . COMPRESSION_TYPE_ZSTD . '](https://en.wikipedia.org/wiki/Zstd), For file size above ' . Storage::human(APP_STORAGE_READ_BUFFER, 0) . ' compression is skipped even if it\'s enabled', true)
@ -235,8 +235,8 @@ App::put('/v1/storage/buckets/:bucketId')
    ->param('name', null, new Text(128), 'Bucket name', false)
    ->param('permissions', null, new Permissions(APP_LIMIT_ARRAY_PARAMS_SIZE), 'An array of permission strings. By default, the current permissions are inherited. [Learn more about permissions](/docs/permissions).', true)
    ->param('fileSecurity', false, new Boolean(true), 'Enables configuring permissions for individual file. A user needs one of file or bucket level permissions to access a file. [Learn more about permissions](/docs/permissions).', true)
-    ->param('enabled', true, new Boolean(true), 'Is bucket enabled?', true)
-    ->param('maximumFileSize', null, new Range(1, (int) App::getEnv('_APP_STORAGE_LIMIT', 0)), 'Maximum file size allowed in bytes. Maximum allowed value is ' . Storage::human((int)App::getEnv('_APP_STORAGE_LIMIT', 0), 0) . '. For self hosted version you can change the limit by changing _APP_STORAGE_LIMIT environment variable.', true)
+    ->param('enabled', true, new Boolean(true), 'Is bucket enabled? When set to \'disabled\', users cannot access the files in this bucket but Server SDKs with and API key can still access the bucket. No files are lost when this is toggled.', true)
+    ->param('maximumFileSize', null, new Range(1, (int) App::getEnv('_APP_STORAGE_LIMIT', 0)), 'Maximum file size allowed in bytes. Maximum allowed value is ' . Storage::human((int)App::getEnv('_APP_STORAGE_LIMIT', 0), 0) . '.', true)
    ->param('allowedFileExtensions', [], new ArrayList(new Text(64), APP_LIMIT_ARRAY_PARAMS_SIZE), 'Allowed file extensions. Maximum of ' . APP_LIMIT_ARRAY_PARAMS_SIZE . ' extensions are allowed, each 64 characters long.', true)
    ->param('compression', COMPRESSION_TYPE_NONE, new WhiteList([COMPRESSION_TYPE_NONE, COMPRESSION_TYPE_GZIP, COMPRESSION_TYPE_ZSTD]), 'Compression algorithm choosen for compression. Can be one of ' . COMPRESSION_TYPE_NONE . ', [' . COMPRESSION_TYPE_GZIP . '](https://en.wikipedia.org/wiki/Gzip), or [' . COMPRESSION_TYPE_ZSTD . '](https://en.wikipedia.org/wiki/Zstd), For file size above ' . Storage::human(APP_STORAGE_READ_BUFFER, 0) . ' compression is skipped even if it\'s enabled', true)
    ->param('encryption', true, new Boolean(true), 'Is encryption enabled? For file size above ' . Storage::human(APP_STORAGE_READ_BUFFER, 0) . ' encryption is skipped even if it\'s enabled', true)
--- a/app/controllers/api/vcs.php
+++ b/app/controllers/api/vcs.php
@ -269,7 +269,7 @@ App::get('/v1/vcs/github/callback')
    ->param('installation_id', '', new Text(256, 0), 'GitHub installation ID', true)
    ->param('setup_action', '', new Text(256, 0), 'GitHub setup actuon type', true)
    ->param('state', '', new Text(2048), 'GitHub state. Contains info sent when starting authorization flow.', true)
-    ->param('code', '', new Text(2048, 0), 'OAuth2 code.', true)
+    ->param('code', '', new Text(2048, 0), 'OAuth2 code. This is a temporary code that the will be later exchanged for an access token.', true)
    ->inject('gitHub')
    ->inject('user')
    ->inject('project')
--- a/docs/references/functions/create-variable.md
+++ b/docs/references/functions/create-variable.md
@ -1 +1 @@
-Create a new function variable. These variables can be accessed within function as environment variable.
+Create a new function environment variable. These variables can be accessed in the function at runtimem as environment variables.
--- a/docs/references/project/create-variable.md
+++ b/docs/references/project/create-variable.md
@ -1 +1 @@
-Create a new project variable.
+Create a new project variable. This variable will be accessible in all Appwrite Functions at runtime.
--- a/docs/references/project/delete-variable.md
+++ b/docs/references/project/delete-variable.md
@ -1 +1 @@
-Delete a project variable by its unique ID.
+Delete a project variable by its unique ID. 
--- a/docs/references/project/list-variables.md
+++ b/docs/references/project/list-variables.md
@ -1 +1 @@
-Get a list of all project variables.
+Get a list of all project variables. These variables will be accessible in all Appwrite Functions at runtime.
--- a/docs/references/project/update-variable.md
+++ b/docs/references/project/update-variable.md
@ -1 +1 @@
-Update project variable by its unique ID.
+Update project variable by its unique ID. This variable will be accessible in all Appwrite Functions at runtime.
--- a/src/Appwrite/Utopia/Response/Model/Collection.php
+++ b/src/Appwrite/Utopia/Response/Model/Collection.php
@ -49,7 +49,7 @@ class Collection extends Model
            ])
            ->addRule('enabled', [
                'type' => self::TYPE_BOOLEAN,
-                'description' => 'Collection enabled.',
+                'description' => 'Collection enabled. Can be \'enabled\' or \'disabled\'. When disabled, the collection is inaccessible to users, but remains accessible to Server SDKs using API keys.',
                'default' => true,
                'example' => false,
            ])
--- a/src/Appwrite/Utopia/Response/Model/Database.php
+++ b/src/Appwrite/Utopia/Response/Model/Database.php
@ -36,7 +36,7 @@ class Database extends Model
            ])
            ->addRule('enabled', [
                'type' => self::TYPE_BOOLEAN,
-                'description' => 'Database enabled.',
+                'description' => 'If database is enabled. Can be \'enabled\' or \'disabled\'. When disabled, the database is inaccessible to users, but remains accessible to Server SDKs using API keys.',
                'default' => true,
                'example' => false,
            ])
--- a/src/Appwrite/Utopia/Response/Model/Func.php
+++ b/src/Appwrite/Utopia/Response/Model/Func.php
@ -51,13 +51,13 @@ class Func extends Model
            ])
            ->addRule('live', [
                'type' => self::TYPE_BOOLEAN,
-                'description' => 'Is function live (deployed with latest config)?',
+                'description' => 'Is the function deployed with the latest configuration? This is set to false if you\'ve changed an environment variable. When the value is false, redeploy the function to update it with the latest configuration.',
                'default' => true,
                'example' => false,
            ])
            ->addRule('logging', [
                'type' => self::TYPE_BOOLEAN,
-                'description' => 'Function logging.',
+                'description' => 'Whether executions will be logged. When set to false, executions will not be logged, but will reduce resource used by your Appwrite project.',
                'default' => true,
                'example' => false,
            ])