Doc Comment in Node js release v8.2 and in page https://github.com/cap-js/docs/blob/main/cds/cdl.md#doc-comments----

[MartinStenzig]

The generation of doc comments into a hdbtable does not seem to work. I don't know if this is considered a bug or a documentation inconsistency.

Here is what I tried to narrow it down:

1. I created a new file with name eam-t.cds and the following content:

entity MEntity {
    key ID : Integer;
    /**
     * The name of the entity
     */
    name : String(100);
    
}; 

2. I then run the command line command: cds c ./db/core/eam-t.cds --docs -2 hdbtable and get

----- MEntity.hdbtable -----
COLUMN TABLE MEntity (
  ID INTEGER NOT NULL,
  name NVARCHAR(100),
  PRIMARY KEY(ID)
)

Based on the documentation I assumed there should be a comment in the name column.

I also tried to "overdue" it and set cds.docs in the package.json, but that does not have any effect.

Interestingly cds c ./db/core/eam-t.cds --docs

{
  definitions: {
    MEntity: {
      kind: 'entity',
      elements: {
        ID: {
          key: true,
          type: 'cds.Integer'
        },
        name: {
          doc: 'The name of the entity',
          type: 'cds.String',
          length: 100
        }
      }
    }
  },
  meta: {
    creator: 'CDS Compiler v5.2.0',
    flavor: 'inferred'
  },
  '$version': '2.0'
}

shows doc as an attribute of name (if I specify --docs).

[renejeglinsky]

Hi Martin,
I tested it and it worked for me. Could you give us the versions you use?

These are my versions:

test
@cap-js/asyncapi	1.0.2
@cap-js/openapi	1.0.5
@sap/cds	8.2.0
@sap/cds-compiler	5.2.0
@sap/cds-dk (global)	8.2.0
@sap/cds-fiori	1.2.7
@sap/cds-foss	5.0.1
@sap/cds-mtxs	2.1.0
@sap/eslint-plugin-cds	3.0.4
Node.js	v20.11.0

[renejeglinsky]

Does it work if you add the following to your package.json?

"hana": {
        "comments": true
    }

[MartinStenzig]

Ahhh, we are getting closer. Once I add hana.comments = true into the cds section of my package JSON AND I use the command line --docs. It seems to add the comment.

BUT just adding cds.docs=true and cds.hana.comments=true without the command line parameter --docs does not compile it with comments. This is what I ultimately want so my comments get deployed.

Thinking that I might be able to adjust my mta.yaml and change the build to npx cds build --docs --production, but when I run this on the command line I get "Invalid option: --docs"

[MartinStenzig]

As for versions:
ds version
@alphaoak/eam-core: 1.0.1
@cap-js/asyncapi: 1.0.2
@cap-js/cds-types: 0.2.0
@cap-js/openapi: 1.0.5
@cap-js/sqlite: 1.7.3
@sap/cds: 8.2.1
@sap/cds-compiler: 5.2.0
@sap/cds-dk: 8.2.0
@sap/cds-dk (global): 8.2.0
@sap/cds-fiori: 1.2.2
@sap/cds-foss: 5.0.0
@sap/cds-hana: 2.0.0
@sap/cds-mtxs: 2.1.0
@sap/eslint-plugin-cds: 3.0.4
Node.js: v20.11.0
home: /Users/martinstenzig/dev/alphaoak/eam-core/node_modules/@sap/cds

[LotharBender]

. . .
BUT just adding cds.docs=true and cds.hana.comments=true without the command line parameter --docs does not compile it with comments. This is what I ultimately want so my comments get deployed.

Thinking that I might be able to adjust my mta.yaml and change the build to npx cds build --docs --production, but when I run this on the command line I get "Invalid option: --docs"

Capire documentation and corresponding implementation in cds are currently inconsistent. Instead of cds.docs=true you have to set cds.cdsc.docs=true.

The --docs option is not supported as cds build CLI option - it can only be set as compiler CLI option.
Can you shed some light on your doc comment scenario - what is the purpose of having doc comments generated in all CSNs?

Note: Enabling hana comments has some consequences you should keep in mind:

• when using HDI Schema Evolution based on hdbmigrationtable new migration versions will be generated whenever the doc comment of the corresponding cds entity is changed
• a new table may get created whenever the doc comment of the corresponding cds entity is changed (causing its entire contents to get copied)

[MartinStenzig]

Perfect, that works!

@renejeglinsky are making the updates to the docu or do you want me to suggest something

[renejeglinsky]

Hi Martin,

Lothar already provided a fix: #1271

Do you agree to close this issue then?

[MartinStenzig]

Yipp, let's close it and thanks for the collaboration.