fix(zmodel): prefer to use triple-slash comments as ZModel documentation

fixes #1816

Author: ymc9

packages/schema/src/language-server/zmodel-documentation-provider.ts

@@ -0,0 +1,16 @@
+import { AstNode, JSDocDocumentationProvider } from 'langium';
+
+/**
+ * Documentation provider that first tries to use triple-slash comments and falls back to JSDoc comments.
+ */
+export class ZModelDocumentationProvider extends JSDocDocumentationProvider {
+    getDocumentation(node: AstNode): string | undefined {
+        // prefer to user triple-slash comments
+        if ('comments' in node && Array.isArray(node.comments) && node.comments.length > 0) {
+            return node.comments.map((c: string) => c.replace(/^[/]*\s*/, '')).join('\n');
+        }
+
+        // fall back to JSDoc comments
+        return super.getDocumentation(node);
+    }
+}

packages/schema/src/language-server/zmodel-module.ts

@@ -27,13 +27,14 @@ import { ZModelValidationRegistry, ZModelValidator } from './validator/zmodel-va
 import { ZModelCodeActionProvider } from './zmodel-code-action';
 import { ZModelCompletionProvider } from './zmodel-completion-provider';
 import { ZModelDefinitionProvider } from './zmodel-definition';
+import { ZModelDocumentationProvider } from './zmodel-documentation-provider';
 import { ZModelFormatter } from './zmodel-formatter';
 import { ZModelHighlightProvider } from './zmodel-highlight';
 import { ZModelHoverProvider } from './zmodel-hover';
 import { ZModelLinker } from './zmodel-linker';
 import { ZModelScopeComputation, ZModelScopeProvider } from './zmodel-scope';
 import { ZModelSemanticTokenProvider } from './zmodel-semantic';
-import ZModelWorkspaceManager from './zmodel-workspace-manager';
+import { ZModelWorkspaceManager } from './zmodel-workspace-manager';
 
 /**
  * Declaration of custom services - add your own service classes here.
@@ -77,6 +78,9 @@ export const ZModelModule: Module<ZModelServices, PartialLangiumServices & ZMode
     parser: {
         GrammarConfig: (services) => createGrammarConfig(services),
     },
+    documentation: {
+        DocumentationProvider: (services) => new ZModelDocumentationProvider(services),
+    },
 };
 
 // this duplicates createDefaultSharedModule except that a custom WorkspaceManager is used

packages/schema/src/language-server/zmodel-workspace-manager.ts

@@ -9,7 +9,7 @@ import { PLUGIN_MODULE_NAME, STD_LIB_MODULE_NAME } from './constants';
 /**
  * Custom Langium WorkspaceManager implementation which automatically loads stdlib.zmodel
  */
-export default class ZModelWorkspaceManager extends DefaultWorkspaceManager {
+export class ZModelWorkspaceManager extends DefaultWorkspaceManager {
     public pluginModels = new Set<string>();
 
     protected async loadAdditionalDocuments(

packages/schema/src/plugins/prisma/schema-generator.ts

@@ -282,13 +282,13 @@ export class PrismaSchemaGenerator {
             this.generateContainerAttribute(model, attr);
         }
 
-        decl.attributes
-            .filter((attr) => attr.decl.ref && !this.isPrismaAttribute(attr))
-            .forEach((attr) => model.addComment('/// ' + this.zModelGenerator.generate(attr)));
-
         // user defined comments pass-through
         decl.comments.forEach((c) => model.addComment(c));
 
+        decl.attributes
+            .filter((attr) => attr.decl.ref && !this.isPrismaAttribute(attr))
+            .forEach((attr) => model.addComment('/// - _' + this.zModelGenerator.generate(attr) + '_'));
+
         // generate relation fields on base models linking to concrete models
         this.generateDelegateRelationForBase(model, decl);
 
@@ -765,9 +765,11 @@ export class PrismaSchemaGenerator {
 
         const nonPrismaAttributes = field.attributes.filter((attr) => attr.decl.ref && !this.isPrismaAttribute(attr));
 
-        const documentations = nonPrismaAttributes.map((attr) => '/// ' + this.zModelGenerator.generate(attr));
+        // user defined comments pass-through
+        const docs: string[] = [...field.comments];
+        docs.push(...nonPrismaAttributes.map((attr) => '/// - _' + this.zModelGenerator.generate(attr) + '_'));
 
-        const result = model.addField(field.name, type, attributes, documentations, addToFront);
+        const result = model.addField(field.name, type, attributes, docs, addToFront);
 
         if (this.mode === 'logical') {
             if (field.attributes.some((attr) => isDefaultWithAuth(attr))) {
@@ -777,8 +779,6 @@ export class PrismaSchemaGenerator {
             }
         }
 
-        // user defined comments pass-through
-        field.comments.forEach((c) => result.addComment(c));
         return result;
     }
 
@@ -898,12 +898,12 @@ export class PrismaSchemaGenerator {
             this.generateContainerAttribute(_enum, attr);
         }
 
-        decl.attributes
-            .filter((attr) => attr.decl.ref && !this.isPrismaAttribute(attr))
-            .forEach((attr) => _enum.addComment('/// ' + this.zModelGenerator.generate(attr)));
-
         // user defined comments pass-through
         decl.comments.forEach((c) => _enum.addComment(c));
+
+        decl.attributes
+            .filter((attr) => attr.decl.ref && !this.isPrismaAttribute(attr))
+            .forEach((attr) => _enum.addComment('/// - _' + this.zModelGenerator.generate(attr) + '_'));
     }
 
     private generateEnumField(_enum: PrismaEnum, field: EnumField) {
@@ -913,8 +913,9 @@ export class PrismaSchemaGenerator {
 
         const nonPrismaAttributes = field.attributes.filter((attr) => attr.decl.ref && !this.isPrismaAttribute(attr));
 
-        const documentations = nonPrismaAttributes.map((attr) => '/// ' + this.zModelGenerator.generate(attr));
-        _enum.addField(field.name, attributes, documentations.concat(field.comments));
+        const docs = [...field.comments];
+        docs.push(...nonPrismaAttributes.map((attr) => '/// - _' + this.zModelGenerator.generate(attr) + '_'));
+        _enum.addField(field.name, attributes, docs);
     }
 }
 

packages/schema/tests/generator/prisma-generator.test.ts

@@ -47,10 +47,35 @@ describe('Prisma generator test', () => {
                 provider = '@core/prisma'
             }
 
+            /// User roles
+            enum Role {
+                /// Admin role
+                ADMIN
+                /// Regular role
+                USER
+
+                @@schema("auth")
+            }
+
+            /// My user model
+            /// defined here
             model User {
-                id String @id
+                /// the id field
+                id String @id @allow('read', this == auth())
+                role Role
 
                 @@schema("auth")
+                @@allow('all', true)
+                @@deny('update', this != auth())
+            }
+
+            /**
+             * My post model
+             * defined here
+             */
+            model Post {
+                id String @id
+                @@schema("public")
             }
         `);
 
@@ -70,6 +95,14 @@ describe('Prisma generator test', () => {
             'extensions = [pg_trgm, postgis(version: "3.3.2"), uuid_ossp(map: "uuid-ossp", schema: "extensions")]'
         );
         expect(content).toContain('schemas = ["auth", "public"]');
+        expect(content).toContain('/// My user model');
+        expect(content).toContain(`/// - _@@allow('all', true)_`);
+        expect(content).toContain(`/// the id field`);
+        expect(content).toContain(`/// - _@allow('read', this == auth())_`);
+        expect(content).not.toContain('/// My post model');
+        expect(content).toContain('/// User roles');
+        expect(content).toContain('/// Admin role');
+        expect(content).toContain('/// Regular role');
         await getDMMF({ datamodel: content });
     });