From 46ef3e532e596797dc1136e47f7600c489d56782 Mon Sep 17 00:00:00 2001
From: Steffen Weinstock <79531202+stewsk@users.noreply.github.com>
Date: Fri, 9 May 2025 11:26:17 +0200
Subject: [PATCH 1/2] (cds 9) Propagation of doc comments

---
 cds/cdl.md | 45 ++++++++++++++++++++++++++++++---------------
 1 file changed, 30 insertions(+), 15 deletions(-)

diff --git a/cds/cdl.md b/cds/cdl.md
index cee2e5532..f127d0598 100644
--- a/cds/cdl.md
+++ b/cds/cdl.md
@@ -304,19 +304,6 @@ entity Employees {
 The text of a doc comment is stored in CSN in the property `doc`.
 When generating OData EDM(X), it appears as value for the annotation `@Core.Description`.
 
-When generating output for deployment to SAP HANA, the first paragraph of a doc comment is translated to the HANA `COMMENT` feature for tables, table columns, and for views (but not for view columns):
-
-```sql
-CREATE TABLE Employees (
-  ID INTEGER,
-  name NVARCHAR(...) COMMENT 'I am the description for "name"'
-) COMMENT 'I am the description for "Employee"'
-```
-
-::: tip
-Propagation of doc comments can be stopped via an empty one: `/** */`.
-:::
-
 In CAP Node.js, doc comments need to be switched on when calling the compiler:
 
 ::: code-group
@@ -331,13 +318,41 @@ cds.compile(..., { docs: true })
 
 :::
 
-::: tip Doc comments are enabled by default in CAP Java.
-In CAP Java, doc comments are automatically enabled by the [CDS Maven Plugin](../java/developing-applications/building#cds-maven-plugin). In generated interfaces they are [converted to corresponding Javadoc comments](../java/assets/cds-maven-plugin-site/generate-mojo.html#documentation).
+::: tip Doc comments are automatically enabled in CAP Java.
+In CAP Java, doc comments are automatically enabled by the [CDS Maven Plugin](../java/developing-applications/building#cds-maven-plugin).
+In generated interfaces they are [converted to corresponding Javadoc comments](../java/assets/cds-maven-plugin-site/generate-mojo.html#documentation).
+:::
+
+
+Doc comments are not propagated by default. For example, a doc comment defined for an entity
+isn't automatically copied to projections of this entity. Propagation can be switched on:
+
+__TODO__ verify option name
+
+::: code-group
+
+```sh [CLI]
+cds compile foo.cds --doscs --propagate-docs
+```
+
+```js [JavaScript]
+cds.compile(..., { docs: true, propagateDocs: true })
+```
+
 :::
 
+When switched on, propagation of doc comments can selectively be stopped via an empty one: `/** */`.
 
 
+When generating output for deployment to SAP HANA, the first paragraph of a doc comment is translated
+to the HANA `COMMENT` feature for tables, table columns, and for views (but not for view columns):
 
+```sql
+CREATE TABLE Employees (
+  ID INTEGER,
+  name NVARCHAR(...) COMMENT 'I am the description for "name"'
+) COMMENT 'I am the description for "Employee"'
+```
 
 
 ## Entities & Type Definitions

From 802c681db0ea8d59ebffa0ae6a636e19625566d1 Mon Sep 17 00:00:00 2001
From: Steffen Weinstock <79531202+stewsk@users.noreply.github.com>
Date: Fri, 9 May 2025 14:42:18 +0200
Subject: [PATCH 2/2] Update cds/cdl.md

Co-authored-by: Andre Meyering <andre.meyering@sap.com>
---
 cds/cdl.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/cds/cdl.md b/cds/cdl.md
index f127d0598..1d44722e0 100644
--- a/cds/cdl.md
+++ b/cds/cdl.md
@@ -332,7 +332,7 @@ __TODO__ verify option name
 ::: code-group
 
 ```sh [CLI]
-cds compile foo.cds --doscs --propagate-docs
+cds compile foo.cds --docs --propagate-docs
 ```
 
 ```js [JavaScript]