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/3] (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/3] Update cds/cdl.md Co-authored-by: Andre Meyering --- 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] From 9248a7f655f4c5783288e07ead93723ebc9dd728 Mon Sep 17 00:00:00 2001 From: Steffen Weinstock <79531202+stewsk@users.noreply.github.com> Date: Fri, 16 May 2025 20:32:33 +0200 Subject: [PATCH 3/3] update --- cds/cdl.md | 25 +++---------------------- 1 file changed, 3 insertions(+), 22 deletions(-) diff --git a/cds/cdl.md b/cds/cdl.md index 1d44722e0..c18c0dda1 100644 --- a/cds/cdl.md +++ b/cds/cdl.md @@ -302,7 +302,9 @@ 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`. +Doc comments are not propagated. For example, a doc comment defined for an entity +isn't automatically copied to projections of this entity. +When generating OData EDM(X), doc comments are translated to the annotation `@Core.Description`. In CAP Node.js, doc comments need to be switched on when calling the compiler: @@ -323,27 +325,6 @@ In CAP Java, doc comments are automatically enabled by the [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 --docs --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):