Update comment and database-comment

Author: Blargian

docs/en/sql-reference/statements/alter/comment.md

@@ -1,24 +1,28 @@
 ---
-description: 'Documentation for ALTER TABLE ... MODIFY COMMENT'
-sidebar_label: 'COMMENT'
+description: 'Documentation for ALTER TABLE ... MODIFY COMMENT which allow
+adding, modifying, or removing table comments'
+sidebar_label: 'ALTER TABLE ... MODIFY COMMENT'
 sidebar_position: 51
 slug: /sql-reference/statements/alter/comment
 title: 'ALTER TABLE ... MODIFY COMMENT'
+keywords: ['ALTER TABLE', 'MODIFY COMMENT']
 ---
 
 # ALTER TABLE ... MODIFY COMMENT
 
-Adds, modifies, or removes comment to the table, regardless if it was set before or not. Comment change is reflected in both [system.tables](../../../operations/system-tables/tables.md) and `SHOW CREATE TABLE` query.
+Adds, modifies, or removes a table comment, regardless of whether it was set 
+before or not. The comment change is reflected in both [`system.tables`](../../../operations/system-tables/tables.md) 
+and in the `SHOW CREATE TABLE` query.
 
-**Syntax**
+## Syntax {#syntax}
 
 ```sql
 ALTER TABLE [db].name [ON CLUSTER cluster] MODIFY COMMENT 'Comment'
 ```
 
-**Examples**
+## Examples {#examples}
 
-Creating a table with comment (for more information, see the [COMMENT](/sql-reference/statements/create/table#comment-clause) clause):
+To create a table with a comment:
 
 ```sql
 CREATE TABLE table_with_comment
@@ -30,38 +34,56 @@ ENGINE = Memory()
 COMMENT 'The temporary table';
 ```
 
-Modifying the table comment:
+To modify the table comment:
 
 ```sql
-ALTER TABLE table_with_comment MODIFY COMMENT 'new comment on a table';
-SELECT comment FROM system.tables WHERE database = currentDatabase() AND name = 'table_with_comment';
+ALTER TABLE table_with_comment 
+MODIFY COMMENT 'new comment on a table';
 ```
 
-Output of a new comment:
+To view the modified comment:
 
-```text
+```sql title="Query"
+SELECT comment 
+FROM system.tables 
+WHERE database = currentDatabase() AND name = 'table_with_comment';
+```
+
+```text title="Response"
 ┌─comment────────────────┐
 │ new comment on a table │
 └────────────────────────┘
 ```
 
-Removing the table comment:
+To remove the table comment:
 
 ```sql
 ALTER TABLE table_with_comment MODIFY COMMENT '';
-SELECT comment FROM system.tables WHERE database = currentDatabase() AND name = 'table_with_comment';
 ```
 
-Output of a removed comment:
+To verify that the comment was removed:
+
+```sql title="Query"
+SELECT comment 
+FROM system.tables 
+WHERE database = currentDatabase() AND name = 'table_with_comment';
+```
 
-```text
+```text title="Response"
 ┌─comment─┐
 │         │
 └─────────┘
 ```
 
-**Caveats**
+## Caveats {#caveats}
+
+For Replicated tables, the comment can be different on different replicas. 
+Modifying the comment applies to a single replica.
+
+The feature is available since version 23.9. It does not work in previous 
+ClickHouse versions.
 
-For Replicated tables, the comment can be different on different replicas. Modifying the comment applies to a single replica.
+## Related content {#related-content}
 
-The feature is available since version 23.9. It does not work in previous ClickHouse versions.
+- [`COMMENT`](/sql-reference/statements/create/table#comment-clause) clause
+- [`ALTER DATABASE ... MODIFY COMMENT`](./database-comment.md)

docs/en/sql-reference/statements/alter/database-comment.md

@@ -1,55 +1,76 @@
 ---
-description: 'Documentation for ALTER DATABASE ... MODIFY COMMENT Statements'
+description: 'Documentation for ALTER DATABASE ... MODIFY COMMENT statements
+which allow adding, modifying, or removing database comments.'
 slug: /sql-reference/statements/alter/database-comment
 sidebar_position: 51
-sidebar_label: 'UPDATE'
+sidebar_label: 'ALTER DATABASE ... MODIFY COMMENT'
 title: 'ALTER DATABASE ... MODIFY COMMENT Statements'
+keywords: ['ALTER DATABASE', 'MODIFY COMMENT']
 ---
 
 # ALTER DATABASE ... MODIFY COMMENT
 
-Adds, modifies, or removes comment to the database, regardless of whether it was set before. Comment change is reflected in both [system.databases](/operations/system-tables/databases.md) and `SHOW CREATE DATABASE` query.
+Adds, modifies, or removes a database comment, regardless of whether it was set
+before or not. The comment change is reflected in both [`system.databases`](/operations/system-tables/databases.md) 
+and the `SHOW CREATE DATABASE` query.
 
-**Syntax**
+## Syntax {#syntax}
 
 ``` sql
 ALTER DATABASE [db].name [ON CLUSTER cluster] MODIFY COMMENT 'Comment'
 ```
 
-**Examples**
+## Examples {#examples}
 
-Creating a DATABASE with comment (for more information, see the [COMMENT](/sql-reference/statements/create/table#comment-clause) clause):
+To create a `DATABASE` with a comment:
 
 ``` sql
 CREATE DATABASE database_with_comment ENGINE = Memory COMMENT 'The temporary database';
 ```
 
-Modifying the table comment:
+To modify the comment:
 
 ``` sql
-ALTER DATABASE database_with_comment MODIFY COMMENT 'new comment on a database';
-SELECT comment FROM system.databases WHERE name = 'database_with_comment';
+ALTER DATABASE database_with_comment 
+MODIFY COMMENT 'new comment on a database';
 ```
 
-Output of a new comment:
+To view the modified comment:
+
+```sql
+SELECT comment 
+FROM system.databases 
+WHERE name = 'database_with_comment';
+```
 
 ```text
 ┌─comment─────────────────┐
 │ new comment on database │
 └─────────────────────────┘
 ```
 
-Removing the database comment:
+To remove the database comment:
 
 ``` sql
-ALTER DATABASE database_with_comment MODIFY COMMENT '';
-SELECT comment FROM system.databases WHERE  name = 'database_with_comment';
+ALTER DATABASE database_with_comment 
+MODIFY COMMENT '';
 ```
 
-Output of a removed comment:
+To verify that the comment was removed:
 
-```text
+```sql title="Query"
+SELECT comment 
+FROM system.databases 
+WHERE  name = 'database_with_comment';
+```
+
+```text title="Response"
 ┌─comment─┐
 │         │
 └─────────┘
 ```
+
+## Related content {#related-content}
+
+- [`COMMENT`](/sql-reference/statements/create/table#comment-clause) clause
+- [`ALTER TABLE ... MODIFY COMMENT`](./comment.md)