support generated java comments by solidity devdoc.

src/main/java/org/fisco/bcos/codegen/CodeGenMain.java

@@ -107,6 +107,11 @@ static class PicocliRunner implements Runnable {
                 required = true)
         private File smBinFile;
 
+        @Option(
+                names = {"-d", "--devdoc"},
+                description = "solidity devdoc file generated by NatSpec style comments.")
+        private File devdocFile;
+
         @Option(
                 names = {"-o", "--outputDir"},
                 description = "destination base directory.",
@@ -134,7 +139,12 @@ public void run() {
             if (version.equals(Version.V2)) {
                 try {
                     new org.fisco.bcos.codegen.v2.wrapper.SolidityContractGenerator(
-                                    binFile, smBinFile, abiFile, destinationFileDir, packageName)
+                                    binFile,
+                                    smBinFile,
+                                    abiFile,
+                                    devdocFile,
+                                    destinationFileDir,
+                                    packageName)
                             .generateJavaFiles();
                 } catch (Exception e) {
                     org.fisco.bcos.codegen.v2.utils.CodeGenUtils.exitError(e);
@@ -145,6 +155,7 @@ public void run() {
                                     binFile,
                                     smBinFile,
                                     abiFile,
+                                    devdocFile,
                                     destinationFileDir,
                                     packageName,
                                     enableAsyncCall,

src/main/java/org/fisco/bcos/codegen/v2/utils/Devdoc.java

@@ -0,0 +1,54 @@
+package org.fisco.bcos.codegen.v2.utils;
+
+import java.util.Map;
+
+public class Devdoc {
+    private String details;
+    private Map<String, Method> methods;
+
+    public String getDetails() {
+        return details;
+    }
+
+    public void setDetails(String details) {
+        this.details = details;
+    }
+
+    public Map<String, Method> getMethods() {
+        return methods;
+    }
+
+    public void setMethods(Map<String, Method> methods) {
+        this.methods = methods;
+    }
+
+    public static class Method {
+        private String details;
+        private Map<String, String> params;
+        private Map<String, String> returns;
+
+        public String getDetails() {
+            return details;
+        }
+
+        public void setDetails(String details) {
+            this.details = details;
+        }
+
+        public Map<String, String> getParams() {
+            return params;
+        }
+
+        public void setParams(Map<String, String> params) {
+            this.params = params;
+        }
+
+        public Map<String, String> getReturns() {
+            return returns;
+        }
+
+        public void setReturns(Map<String, String> returns) {
+            this.returns = returns;
+        }
+    }
+}

src/main/java/org/fisco/bcos/codegen/v2/utils/DocUtils.java

@@ -0,0 +1,74 @@
+package org.fisco.bcos.codegen.v2.utils;
+
+import com.squareup.javapoet.MethodSpec;
+import java.io.File;
+import java.io.IOException;
+import java.util.Map;
+import org.fisco.bcos.codegen.v2.exceptions.CodeGenException;
+import org.fisco.bcos.sdk.abi.wrapper.ABIDefinition;
+import org.fisco.bcos.sdk.transaction.tools.JsonUtils;
+import org.fisco.bcos.sdk.utils.StringUtils;
+
+public class DocUtils {
+
+    public static Devdoc.Method getMethod(Devdoc devdoc, ABIDefinition functionDefinition) {
+        if (devdoc != null && devdoc.getMethods() != null) {
+            return devdoc.getMethods().get(functionDefinition.getMethodSignatureAsString());
+        }
+
+        return null;
+    }
+
+    public static void addMethodComments(Devdoc.Method method, MethodSpec.Builder methodBuilder) {
+        if (method == null) {
+            return;
+        }
+
+        // add comments for method
+        if (!StringUtils.isEmpty(method.getDetails())) {
+            methodBuilder.addJavadoc("$L \n", method.getDetails());
+        }
+    }
+
+    public static void addParamsComments(Devdoc.Method method, MethodSpec.Builder methodBuilder) {
+        if (method == null) {
+            return;
+        }
+
+        // add comments for params
+        Map<String, String> params = method.getParams();
+        if (params != null) {
+            for (String p : params.keySet()) {
+                if (!StringUtils.isEmpty(params.get(p))) {
+                    methodBuilder.addJavadoc("@param $N $L \n", p, params.get(p));
+                }
+            }
+        }
+    }
+
+    public static void addReturnsComments(
+            String comments, Devdoc.Method method, MethodSpec.Builder methodBuilder) {
+        if (method == null) {
+            return;
+        }
+
+        // add comments for returns
+        Map<String, String> returns = method.getReturns();
+        if (returns != null) {
+            for (String r : returns.keySet()) {
+                if (!StringUtils.isEmpty(returns.get(r))) {
+                    methodBuilder.addJavadoc("$L $N $L \n", comments, r, returns.get(r));
+                }
+            }
+        }
+    }
+
+    public static Devdoc convertDevDoc(File devdocFile) throws CodeGenException, IOException {
+        if (devdocFile != null && devdocFile.exists()) {
+            byte[] devdocBytes = CodeGenUtils.readBytes(devdocFile);
+            return JsonUtils.fromJson(new String(devdocBytes), Devdoc.class);
+        } else {
+            return null;
+        }
+    }
+}

src/main/java/org/fisco/bcos/codegen/v2/wrapper/SolidityContractGenerator.java

@@ -17,6 +17,7 @@
 import java.io.IOException;
 import org.fisco.bcos.codegen.v2.exceptions.CodeGenException;
 import org.fisco.bcos.codegen.v2.utils.CodeGenUtils;
+import org.fisco.bcos.codegen.v2.utils.DocUtils;
 
 /** Java wrapper source code generator for Solidity ABI format. */
 public class SolidityContractGenerator {
@@ -46,18 +47,21 @@ public class SolidityContractGenerator {
     private final File binFile;
     private final File smBinFile;
     private final File abiFile;
+    private final File devdocFile;
     private final File destinationDir;
     private final String basePackageName;
 
     public SolidityContractGenerator(
             File binFile,
             File smBinFile,
             File abiFile,
+            File devdocFile,
             File destinationDir,
             String basePackageName) {
         this.binFile = binFile;
         this.smBinFile = smBinFile;
         this.abiFile = abiFile;
+        this.devdocFile = devdocFile;
         this.destinationDir = destinationDir;
         this.basePackageName = basePackageName;
     }
@@ -77,6 +81,7 @@ public void generateJavaFiles() throws IOException, ClassNotFoundException, Code
                         new String(binary),
                         new String(smBinary),
                         new String(abiBytes),
+                        DocUtils.convertDevDoc(devdocFile),
                         destinationDir.toString(),
                         basePackageName);
     }

src/main/java/org/fisco/bcos/codegen/v2/wrapper/SolidityContractWrapper.java

@@ -43,6 +43,8 @@
 import javax.lang.model.element.Modifier;
 import org.fisco.bcos.codegen.v2.exceptions.CodeGenException;
 import org.fisco.bcos.codegen.v2.utils.CodeGenUtils;
+import org.fisco.bcos.codegen.v2.utils.Devdoc;
+import org.fisco.bcos.codegen.v2.utils.DocUtils;
 import org.fisco.bcos.sdk.abi.FunctionEncoder;
 import org.fisco.bcos.sdk.abi.FunctionReturnDecoder;
 import org.fisco.bcos.sdk.abi.TypeReference;
@@ -109,15 +111,19 @@ public class SolidityContractWrapper {
     private static final HashMap<Integer, TypeName> structClassNameMap = new HashMap<>();
     private static final List<ABIDefinition.NamedType> structsNamedTypeList = new ArrayList<>();
 
+    private Devdoc devdoc;
+
     public void generateJavaFiles(
             String contractName,
             String bin,
             String smBin,
             String abi,
+            Devdoc devdoc,
             String destinationDir,
             String basePackageName)
             throws IOException, ClassNotFoundException, UnsupportedOperationException,
                     CodeGenException {
+        this.devdoc = devdoc;
         String className = StringUtils.capitaliseFirstLetter(contractName);
 
         logger.info("bin: {}", bin);
@@ -745,6 +751,22 @@ private MethodSpec buildFunction(ABIDefinition functionDefinition)
             buildTransactionFunction(functionDefinition, methodBuilder, inputParams);
         }
 
+        Devdoc.Method method = DocUtils.getMethod(devdoc, functionDefinition);
+        DocUtils.addMethodComments(method, methodBuilder);
+        DocUtils.addParamsComments(method, methodBuilder);
+        if (functionDefinition.isConstant()) {
+            DocUtils.addReturnsComments("@return", method, methodBuilder);
+        } else {
+            methodBuilder.addJavadoc(
+                    "@return TransactionReceipt Get more transaction info (e.g. txhash, block) from TransactionReceipt \n");
+            if (functionDefinition.getOutputs().size() > 0) {
+                methodBuilder.addJavadoc(
+                        "    use get$NOutput(transactionReceipt) to get outputs \n",
+                        StringUtils.capitaliseFirstLetter(functionDefinition.getName()));
+            }
+            DocUtils.addReturnsComments("    tuple", method, methodBuilder);
+        }
+
         return methodBuilder.build();
     }
 
@@ -786,6 +808,33 @@ private MethodSpec buildFunctionWithCallback(ABIDefinition functionDefinition)
             buildTransactionFunctionWithCallback(functionDefinition, methodBuilder, inputParams);
         }
 
+        Devdoc.Method method = DocUtils.getMethod(devdoc, functionDefinition);
+        DocUtils.addMethodComments(method, methodBuilder);
+        DocUtils.addParamsComments(method, methodBuilder);
+        if (functionDefinition.isConstant()) {
+            // add comments for constant call callback
+            methodBuilder.addJavadoc(
+                    "@param callback Get method outputs from constant call callback onResponse(List<Type> types) \n");
+
+            // add comments for constant call callback outputs
+            DocUtils.addReturnsComments("    callback.onResponse(types)", method, methodBuilder);
+        } else {
+            // add comments for transaction call callback
+            methodBuilder.addJavadoc(
+                    "@param callback Get TransactionReceipt from TransactionCallback onResponse(TransactionReceipt receipt) \n");
+
+            if (functionDefinition.getOutputs().size() > 0) {
+                methodBuilder.addJavadoc(
+                        "    use get$NOutput(transactionReceipt) to get outputs \n",
+                        StringUtils.capitaliseFirstLetter(functionDefinition.getName()));
+            }
+
+            // add comments for how to get outputs in transaction call callback
+            DocUtils.addReturnsComments("    tuple", method, methodBuilder);
+            methodBuilder.addJavadoc(
+                    "@return txHash Transaction hash of current transaction call \n");
+        }
+
         return methodBuilder.build();
     }
 

src/main/java/org/fisco/bcos/codegen/v3/utils/Devdoc.java

@@ -0,0 +1,54 @@
+package org.fisco.bcos.codegen.v3.utils;
+
+import java.util.Map;
+
+public class Devdoc {
+    private String details;
+    private Map<String, Method> methods;
+
+    public String getDetails() {
+        return details;
+    }
+
+    public void setDetails(String details) {
+        this.details = details;
+    }
+
+    public Map<String, Method> getMethods() {
+        return methods;
+    }
+
+    public void setMethods(Map<String, Method> methods) {
+        this.methods = methods;
+    }
+
+    public static class Method {
+        private String details;
+        private Map<String, String> params;
+        private Map<String, String> returns;
+
+        public String getDetails() {
+            return details;
+        }
+
+        public void setDetails(String details) {
+            this.details = details;
+        }
+
+        public Map<String, String> getParams() {
+            return params;
+        }
+
+        public void setParams(Map<String, String> params) {
+            this.params = params;
+        }
+
+        public Map<String, String> getReturns() {
+            return returns;
+        }
+
+        public void setReturns(Map<String, String> returns) {
+            this.returns = returns;
+        }
+    }
+}