fix: add example, checkBlank, nullable and sensitive to description

lib/generator.js

@@ -6,6 +6,7 @@
 const DSL = require('@darabonba/parser');
 const xml2js = require('xml2js');
 const Entities = require('html-entities').XmlEntities;
+const Annotation = require('@darabonba/annotation-parser');
 
 const REQUEST = 'request_';
 const RESPONSE = 'response_';
@@ -16,10 +17,10 @@
   _lowerFirst,
   _subModelName,
   remove,
-  _upperFirst
+  _upperFirst,
+  md2Html
 } = require('./helper');
 
-
 function collectionType(name) {
   if (name === 'Object') {
     return '?';
@@ -70,7 +71,7 @@
     'artifactId', 'version'
   ];
   needParamsKeys.forEach(key => {
     if (params[key] === undefined) {
       params[key] = '';
     }
   });
@@ -127,6 +128,7 @@
     this.output = '';
     this.outputDir = this.config.outputDir;
     this.exec = option.exec;
+    this.editable = option.editable;
     this.enableMinimizeModelName = option.enableMinimizeModelName || option.java.enableMinimizeModelName;
     this.typedef = option.java.typedef || {};
     if (!this.outputDir) {
@@ -539,10 +541,94 @@
     }
     let comments = DSL.comment.getFrontComments(this.comments, annotation.index);
     this.visitComments(comments, level);
-    annotation.value.split('\n').forEach((line) => {
-      this.emit(`${line}`, level);
-      this.emit(`\n`);
+    var ast = Annotation.parse(annotation.value);
+    var description = ast.items.find((item) => {
+      return item.type === 'description';
+    });
+    var summary = ast.items.find((item) => {
+      return item.type === 'summary';
+    });
+    var _return = ast.items.find((item) => {
+      return item.type === 'return';
+    });
+    var deprecated = ast.items.find((item) => {
+      return item.type === 'deprecated';
     });
+    var params = ast.items.filter((item) => {
+      return item.type === 'param';
+    }).map((item) => {
+      return {
+        name: item.name.id,
+        text: item.text.text.trimEnd()
+      };
+    });
+    var throws = ast.items.filter((item) => {
+      return item.type === 'throws';
+    }).map((item) => {
+      return item.text.text.trimEnd();
+    });
+
+    var descriptionText = description ? description.text.text : '';
+    var summaryText = summary ? summary.text.text : '';
+    var returnText = _return ? _return.text.text.trimEnd() : '';
+    let hasNextSection = false;
+    this.emit(`/**\n`, level);
+    if (descriptionText !== '') {
+      this.emit(` * <b>description</b> :\n`, level);
+      const descriptionTexts = md2Html(descriptionText).trimEnd();
+      descriptionTexts.split('\n').forEach((line) => {
+        this.emit(` * ${line}\n`, level);
+      });
+      hasNextSection = true;
+    }
+    if (summaryText !== '') {
+      if (hasNextSection) {
+        this.emit(` * \n`, level);
+      }
+      this.emit(` * <b>summary</b> : \n`, level);
+      const summaryTexts = md2Html(summaryText).trimEnd();
+      summaryTexts.split('\n').forEach((line) => {
+        this.emit(` * ${line}\n`, level);
+      });
+      hasNextSection = true;
+    }
+    if (deprecated) {
+      if (hasNextSection) {
+        this.emit(` * \n`, level);
+      }
+      if (deprecated.text.text.trimEnd() === '') {
+        this.emit(` * @deprecated\n`, level);
+      } else {
+        this.emit(` * @deprecated ${deprecated.text.text.trimEnd()}\n`, level);
+      }
+      hasNextSection = true;
+    }
+    if (params.length > 0) {
+      if (hasNextSection) {
+        this.emit(` * \n`, level);
+      }
+      params.forEach((item) => {
+        this.emit(` * @param ${item.name} ${item.text}\n`, level);
+      });
+      hasNextSection = true;
+    }
+    if (returnText !== '') {
+      this.emit(` * @return ${returnText}\n`, level);
+      hasNextSection = true;
+    }
+    if (throws.length > 0) {
+      if (hasNextSection) {
+        this.emit(` * \n`, level);
+      }
+      throws.forEach((item) => {
+        this.emit(` * @throws ${item}\n`, level);
+      });
+    }
+    this.emit(` */`, level);
+    this.emit(`\n`);
+    if (deprecated) {
+      this.emit(`@Deprecated\n`, level);
+    }
   }
 
   visitAPIBody(ast, level) {
@@ -693,22 +779,60 @@
       const value = node.fieldValue;
       const realName = getAttr(node, 'name') || _name(node.fieldName);
       const description = getAttr(node, 'description');
+      const example = getAttr(node, 'example');
+      const checkBlank = getAttr(node, 'checkBlank');
+      const nullable = getAttr(node, 'nullable');
+      const sensitive = getAttr(node, 'sensitive');
       const pattern = getAttr(node, 'pattern') || '';
       const maxLength = getAttr(node, 'maxLength') || 0;
       const minLength = getAttr(node, 'minLength') || 0;
       const maximum = getAttr(node, 'maximum') || 0;
       const minimum = getAttr(node, 'minimum') || 0;
       const required = node.required || false;
       const deprecated = getAttr(node, 'deprecated');
-      if (description) {
-        let descriptions = description.split('\n');
+      let hasNextSection = false;
+      if (description || example || typeof checkBlank !== 'undefined' || typeof nullable !== 'undefined' || typeof sensitive !== 'undefined') {
         this.emit('/**\n', level);
-        for (let j = 0; j < descriptions.length; j++) {
-          if (descriptions[j] === '') {
-            this.emit(` * <br>\n`, level);
-          } else {
-            this.emit(` * <p>${descriptions[j]}</p>\n`, level);
+        if (description) {
+          const descriptions = md2Html(description).trimEnd().split('\n');
+          for (let j = 0; j < descriptions.length; j++) {
+            this.emit(` * ${descriptions[j]}\n`, level);
+          }
+          hasNextSection = true;
+        }
+        if (example) {
+          if (hasNextSection) {
+            this.emit(' * \n', level);
+          }
+          const examples = md2Html(example).trimEnd().split('\n');
+          this.emit(' * <strong>example:</strong>\n', level);
+          for (let j = 0; j < examples.length; j++) {
+            this.emit(` * ${examples[j]}\n`, level);
           }
+          hasNextSection = true;
+        }
+        if (typeof checkBlank !== 'undefined') {
+          if (hasNextSection) {
+            this.emit(' * \n', level);
+          }
+          this.emit(' * <strong>check if is blank:</strong>\n', level);
+          this.emit(` * <p>${checkBlank}</p>\n`, level);
+          hasNextSection = true;
+        }
+        if (typeof nullable !== 'undefined') {
+          if (hasNextSection) {
+            this.emit(' * \n', level);
+          }
+          this.emit(' * <strong>if can be null:</strong>\n', level);
+          this.emit(` * <p>${nullable}</p>\n`, level);
+          hasNextSection = true;
+        }
+        if (typeof sensitive !== 'undefined') {
+          if (hasNextSection) {
+            this.emit(' * \n', level);
+          }
+          this.emit(' * <strong>if sensitive:</strong>\n', level);
+          this.emit(` * <p>${sensitive}</p>\n`, level);
         }
         this.emit(' */\n', level);
       }
@@ -1608,21 +1732,26 @@
   visitImport() { }
 
   importBefore(level) {
-    this.emit(`// This file is auto-generated, don't edit it. Thanks.\n`, level);
+    if (this.editable !== true) {
+      this.emit(`// This file is auto-generated, don't edit it. Thanks.\n`, level);
+    }
   }
-
   modelBefore() {
-    this.emit(`// This file is auto-generated, don't edit it. Thanks.
-package ${this.package}.models;
+    if (this.editable !== true) {
+      this.emit(`// This file is auto-generated, don't edit it. Thanks.\n`);
+    }
+    this.emit(`package ${this.package}.models;
 
 import com.aliyun.tea.*;
 
 `);
   }
 
   apiBefore(extendParam, extendsClass, hasAPI, level) {
-    this.emit(`// This file is auto-generated, don't edit it. Thanks.
-package ${this.package};
+    if (this.editable !== true) {
+      this.emit(`// This file is auto-generated, don't edit it. Thanks.\n`);
+    }
+    this.emit(`package ${this.package};
 
 import com.aliyun.tea.*;
 `);

lib/helper.js

@@ -2,6 +2,12 @@
 
 const fs = require('fs');
 const path = require('path');
+const marked = require('marked');
+marked.use({
+  mangle: false,
+  headerIds: false
+});
+
 
 function _name(str) {
   const keywords = ['default', 'abstract', 'assert',
@@ -141,7 +147,12 @@ function remove(...filesPath) {
   });
 }
 
+function md2Html(mdText) {
+  let htmlText = marked.parse(mdText).trimEnd();
+  return htmlText;
+}
+
 module.exports = {
   _name, _type,
-  _lowerFirst, _subModelName, remove, _upperFirst
+  _lowerFirst, _subModelName, remove, _upperFirst, md2Html
 };

package.json

@@ -26,8 +26,10 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@darabonba/parser": "^1.2.9",
+    "@darabonba/annotation-parser": "^1.0.0",
     "html-entities": "^1.3.1",
-    "xml2js": "^0.5.0"
+    "xml2js": "^0.5.0",
+    "marked": "6.0.0"
   },
   "files": [
     "lib",
@@ -37,4 +39,4 @@
   "engines": {
     "node": ">= 12"
   }
-}
+}

test/fixtures/comment/Client.java

@@ -1,4 +1,3 @@
-// This file is auto-generated, don't edit it. Thanks.
 package com.aliyun.test;
 
 import com.aliyun.tea.*;
@@ -14,8 +13,9 @@ public class Client {
 
     public java.util.List<String> _a;
     /**
-      Init Func
-    */
+     * <b>description</b> :
+     * <p>Init Func</p>
+     */
     // comment between init and annotation
     public Client(String a, String b) throws Exception {
         // string declate comment
@@ -35,8 +35,9 @@ public Client(String a, String b) throws Exception {
     }
 
     /**
-      testAPI
-    */
+     * <b>description</b> :
+     * <p>testAPI</p>
+     */
     //testAPI comment one
     //testAPI comment two
     public void testAPI() throws Exception {
@@ -145,16 +146,18 @@ public void addResponseInterceptor(ResponseInterceptor interceptor) {
     }
 
     /**
-      staticFunc
-    */
+     * <b>description</b> :
+     * <p>staticFunc</p>
+     */
     // staticFunc comment
     public static void staticFunc() throws Exception {
         java.util.List<Object> a = new java.util.ArrayList<>();
     }
 
     /**
-      testFunc
-    */
+     * <b>description</b> :
+     * <p>testFunc</p>
+     */
     // testFunc comment
     public static void testFunc() throws Exception {
         // empty comment1
@@ -163,13 +166,41 @@ public static void testFunc() throws Exception {
 
     // Deprecated
     /**
-      * @deprecated : deprecatedFunc is deprecated.
-      *
-      * @param test string
-      * @return void
+     * <b>description</b> :
+     * <p>Queries available Alibaba Cloud regions. The natural language that is used to filter responses. For more information, visit <a href="https://tools.ietf.org/html/rfc7231">RFC 7231</a>. Valid values:</p>
+     * <ul>
+     * <li>zh-CN: Chinese</li>
+     * <li>en-US: English</li>
+     * <li>ja: Japanese</li>
+     * </ul>
+     * <p>Default value: zh-CN.</p>
+     * <blockquote>
+     * <p>这是Note的内容</p>
+     * </blockquote>
+     * <blockquote>
+     * <p>Notice: 这是注意的内容</p>
+     * </blockquote>
+     * 
+     * <b>summary</b> : 
+     * <p>Queries available Alibaba Cloud regions. The natural language that is used to filter responses. For more information, visit <a href="https://tools.ietf.org/html/rfc7231">RFC 7231</a>. Valid values:</p>
+     * <ul>
+     * <li>zh-CN: Chinese</li>
+     * <li>en-US: English</li>
+     * <li>ja: Japanese</li>
+     * </ul>
+     * 
+     * @deprecated deprecatedFunc is deprecated.
+     * 
+     * @param test string
+     * @param _test string
+     * @return void
+     * 
+     * @throws InternalError Server error. 500 服务器端出现未知异常。
+     * @throws StackNotFound The Stack (%(stack_name)s) could not be found.  404 资源栈不存在。
      */
+    @Deprecated
     // Deprecated
-    public static void deprecatedFunc(String test) throws Exception {
+    public static void deprecatedFunc(String test, String _test) throws Exception {
         // empty comment1
         // empty comment2
     }

test/fixtures/comment/Darafile

@@ -3,6 +3,7 @@
     "name": "main",
     "version": "0.0.1",
     "main": "./main.dara",
+    "editable":true,
     "libraries": {
         "Source": "alibabacloud:Import:*"
     },