DOCS-functions-codeclean (#343)

Initial update as I apply code formatting and improving important
information using note and important markers.

Author: Andriciuc

contrib/pg_tde/documentation/docs/functions.md

@@ -76,15 +76,39 @@ The Vault provider connects to a HashiCorp Vault or an OpenBao server, and store
 Use the following functions to add the Vault provider:
 
 ```sql
-SELECT pg_tde_add_database_key_provider_vault_v2('provider-name','secret_token','url','mount','ca_path');
-SELECT pg_tde_add_global_key_provider_vault_v2('provider-name','secret_token','url','mount','ca_path');
+SELECT pg_tde_add_database_key_provider_vault_v2(
+  'provider-name',
+  'secret_token',
+  'url','mount',
+  'ca_path'
+);
+
+SELECT pg_tde_add_global_key_provider_vault_v2(
+  'provider-name',
+  'secret_token',
+  'url','mount',
+  'ca_path'
+);
 ```
 
 These functions change the Vault provider:
 
 ```sql
-SELECT pg_tde_change_database_key_provider_vault_v2('provider-name','secret_token','url','mount','ca_path');
-SELECT pg_tde_change_global_key_provider_vault_v2('provider-name','secret_token','url','mount','ca_path');
+SELECT pg_tde_change_database_key_provider_vault_v2(
+  'provider-name',
+  'secret_token',
+  'url',
+  'mount',
+  'ca_path'
+);
+
+SELECT pg_tde_change_global_key_provider_vault_v2(
+  'provider-name',
+  'secret_token',
+  'url',
+  'mount',
+  'ca_path'
+);
 ```
 
 where:
@@ -93,11 +117,12 @@ where:
 * `url` is the URL of the Vault server
 * `mount` is the mount point on the Vault server where the key provider should store the keys
 * `secret_token` is an access token with read and write access to the above mount point
-* [optional] `ca_path` is the path of the CA file used for SSL verification
+* **[optional]** `ca_path` is the path of the CA file used for SSL verification
 
 All parameters can be either strings, or JSON objects [referencing remote parameters](how-to/external-parameters.md).
 
-**Never specify the secret token directly, use a remote parameter instead.**
+!!! important
+    Never specify the secret token directly, use a remote parameter instead.
 
 #### Adding or modifying KMIP providers
 
@@ -155,7 +180,8 @@ where:
 * `client-certificate` is the path to the client certificate.
 * `client-key` is the path to the client key.
 
-The specified access parameters require permission to read and write keys at the server.
+!!! note
+    The specified access parameters require permission to read and write keys at the server.
 
 All parameters can be either strings, or JSON objects [referencing remote parameters](how-to/external-parameters.md).
 
@@ -165,28 +191,44 @@ This provider manages database keys using a local keyfile.
 
 This function is intended for development or quick testing, and stores the keys unencrypted in the specified data file.
 
-**It is not recommended for production.**
+!!! important
+    Local keyfile providers are **not recommended** for production environments, they lack the security and manageability of external key management systems.
 
 Add a local keyfile provider:
 
 ```sql
-SELECT pg_tde_add_database_key_provider_file('provider-name','/path/to/the/key/provider/data.file');
-SELECT pg_tde_add_global_key_provider_file('provider-name','/path/to/the/key/provider/data.file');
+SELECT pg_tde_add_database_key_provider_file(
+  'provider-name',
+  '/path/to/the/key/provider/data.file'
+);
+
+SELECT pg_tde_add_global_key_provider_file(
+  'provider-name',
+  '/path/to/the/key/provider/data.file'
+);
 ```
 
 Change a local keyfile provider:
 
 ```sql
-SELECT pg_tde_change_database_key_provider_file('provider-name','/path/to/the/key/provider/data.file');
-SELECT pg_tde_change_global_key_provider_file('provider-name','/path/to/the/key/provider/data.file');
+SELECT pg_tde_change_database_key_provider_file(
+  'provider-name',
+  '/path/to/the/key/provider/data.file'
+);
+
+SELECT pg_tde_change_global_key_provider_file(
+  'provider-name',
+  '/path/to/the/key/provider/data.file'
+);
 ```
 
 where:
 
 * `provider-name` is the name of the provider. You can specify any name, it's for you to identify the provider.
 * `/path/to/the/key/provider/data.file` is the path to the key provider file.
 
-All parameters can be either strings, or JSON objects [referencing remote parameters](how-to/external-parameters.md).
+!!! note
+    All parameters can be either strings, or JSON objects [referencing remote parameters](how-to/external-parameters.md).
 
 ### Delete a provider
 
@@ -206,7 +248,8 @@ These functions list the details of all key providers for the current database o
 * `pg_tde_list_all_database_key_providers()`
 * `pg_tde_list_all_global_key_providers()`
 
-**All configuration values include possibly sensitive values, such as passwords. Never specify these directly, use the remote configuration option instead.**
+!!! important
+    All configuration values include possibly sensitive values, such as passwords. **Never** specify these directly, use the remote configuration option instead.
 
 ## Principal key management
 
@@ -219,7 +262,11 @@ Princial keys are stored on key providers by the name specified in this function
 Creates or rotates the principal key for the current database using the specified database key provider and key name.
 
 ```sql
-SELECT pg_tde_set_key_using_database_key_provider('name-of-the-key','provider-name','ensure_new_key');
+SELECT pg_tde_set_key_using_database_key_provider(
+  'name-of-the-key',
+  'provider-name',
+  'ensure_new_key'
+);
 ```
 
  The `ensure_new_key` parameter instructs the function how to handle a principal key during key rotation:
@@ -233,7 +280,11 @@ SELECT pg_tde_set_key_using_database_key_provider('name-of-the-key','provider-na
 Creates or rotates the global principal key using the specified global key provider and the key name. This key is used for global settings like WAL encryption.
 
 ```sql
-  SELECT pg_tde_set_key_using_global_key_provider('name-of-the-key','provider-name','ensure_new_key');
+SELECT pg_tde_set_key_using_global_key_provider(
+  'name-of-the-key',
+  'provider-name',
+  'ensure_new_key'
+);
 ```
 
  The `ensure_new_key` parameter instructs the function how to handle a principal key during key rotation:
@@ -247,7 +298,11 @@ Creates or rotates the global principal key using the specified global key provi
 Creates or rotates the server principal key using the specified global key provider. Use this function to set a principal key for WAL encryption.
 
 ```sql
-SELECT pg_tde_set_server_key_using_global_key_provider('name-of-the-key','provider-name','ensure_new_key');
+SELECT pg_tde_set_server_key_using_global_key_provider(
+  'name-of-the-key',
+  'provider-name',
+  'ensure_new_key'
+);
 ```
 
 The `ensure_new_key` parameter instructs the function how to handle a principal key during key rotation:
@@ -263,7 +318,11 @@ Creates or rotates the default principal key for the server using the specified
 The default key is automatically used as a principal key  by any database that doesn't have an individual key provider and key configuration.
 
 ```sql
-SELECT pg_tde_set_default_key_using_global_key_provider('name-of-the-key','provider-name','ensure_new_key');
+SELECT pg_tde_set_default_key_using_global_key_provider(
+  'name-of-the-key',
+  'provider-name',
+  'ensure_new_key'
+);
 ```
 
 The `ensure_new_key` parameter instructs the function how to handle a principal key during key rotation:
@@ -283,13 +342,17 @@ tables and indexes.
 To verify that a table is encrypted, run the following statement:
 
 ```sql
-SELECT pg_tde_is_encrypted('table_name');
+SELECT pg_tde_is_encrypted(
+  'table_name'
+);
 ```
 
 You can also verify if the table in a custom schema is encrypted. Pass the schema name for the function as follows:
 
 ```sql
-SELECT pg_tde_is_encrypted('schema.table_name');
+SELECT pg_tde_is_encrypted(
+  'schema.table_name'
+);
 ```
 
 This can additionally be used to verify that indexes and sequences are encrypted.
@@ -299,23 +362,23 @@ This can additionally be used to verify that indexes and sequences are encrypted
 Displays information about the principal key for the current database, if it exists.
 
 ```sql
-SELECT pg_tde_key_info()
+SELECT pg_tde_key_info();
 ```
 
 ### pg_tde_server_key_info
 
 Displays information about the principal key for the server scope, if exists.
 
 ```sql
-SELECT pg_tde_server_key_info()
+SELECT pg_tde_server_key_info();
 ```
 
 ### pg_tde_default_key_info
 
 Displays the information about the default principal key, if it exists.
 
 ```sql
-SELECT pg_tde_default_key_info()
+SELECT pg_tde_default_key_info();
 ```
 
 ### pg_tde_verify_key
@@ -331,7 +394,7 @@ This function checks that the current database has a properly functional encrypt
 If any of the above checks fail, the function reports an error.
 
 ```sql
-SELECT pg_tde_verify_key()
+SELECT pg_tde_verify_key();
 ```
 
 ### pg_tde_verify_server_key
@@ -347,7 +410,7 @@ This function checks that the server scope has a properly functional encryption
 If any of the above checks fail, the function reports an error.
 
 ```sql
-SELECT pg_tde_verify_server_key()
+SELECT pg_tde_verify_server_key();
 ```
 
 ### pg_tde_verify_default_key
@@ -363,5 +426,5 @@ This function checks that the default key is properly configured, which means:
 If any of the above checks fail, the function reports an error.
 
 ```sql
-SELECT pg_tde_verify_default_key()
+SELECT pg_tde_verify_default_key();
 ```