Java: show the XDR source code in the javadoc (#196)

stellar · May 15, 2024 · 6cd7f3b · 6cd7f3b
1 parent 6b73afa
commit 6cd7f3b
Show file tree

Hide file tree

Showing 40 changed files with 414 additions and 326 deletions.
diff --git a/lib/xdrgen/generators/java.rb b/lib/xdrgen/generators/java.rb
@@ -138,6 +138,7 @@ def render_definition(defn, constants_container)
       def render_nested_definitions(defn, out, post_name="implements XdrElement")
         return unless defn.respond_to? :nested_definitions
         defn.nested_definitions.each{|ndefn|
+          render_source_comment out, ndefn
           case ndefn
           when AST::Definitions::Struct ;
             name = name ndefn
@@ -699,17 +700,12 @@ def render_top_matter(out)
       def render_source_comment(out, defn)
         return if defn.is_a?(AST::Definitions::Namespace)
 
-        out.puts <<-EOS.strip_heredoc
-        // === xdr source ============================================================
-
-        EOS
-
-        out.puts "//  " + defn.text_value.split("\n").join("\n//  ")
-
-        out.puts <<-EOS.strip_heredoc
-
-        //  ===========================================================================
-        EOS
+        out.puts "/**"
+        out.puts " * #{name defn}'s original definition in the XDR file is:"
+        out.puts " * <pre>"
+        out.puts " * " + escape_html(defn.text_value).split("\n").join("\n * ")
+        out.puts " * </pre>"
+        out.puts " */"
       end
 
       def render_base64(return_type, out)
@@ -961,6 +957,14 @@ def name(named)
       def name_string(name)
         name.camelize
       end
+
+      def escape_html(value)
+        value.to_s
+             .gsub('&', '&amp;')
+             .gsub('<', '&lt;')
+             .gsub('>', '&gt;')
+             .gsub('*', '&#42;') # to avoid encountering`*/`
+      end
     end
   end
 end
diff --git a/spec/output/generator_spec_java/block_comments.x/AccountFlags.java b/spec/output/generator_spec_java/block_comments.x/AccountFlags.java
@@ -10,14 +10,15 @@
 import java.io.ByteArrayInputStream;
 import java.io.ByteArrayOutputStream;
 
-// === xdr source ============================================================
-
-//  enum AccountFlags
-//  { // masks for each flag
-//      AUTH_REQUIRED_FLAG = 0x1
-//  };
-
-//  ===========================================================================
+/**
+ * AccountFlags's original definition in the XDR file is:
+ * <pre>
+ * enum AccountFlags
+ * { // masks for each flag
+ *     AUTH_REQUIRED_FLAG = 0x1
+ * };
+ * </pre>
+ */
 public enum AccountFlags implements XdrElement {
   AUTH_REQUIRED_FLAG(1),
   ;

diff --git a/spec/output/generator_spec_java/const.x/TestArray.java b/spec/output/generator_spec_java/const.x/TestArray.java
@@ -11,11 +11,12 @@
 import java.io.ByteArrayOutputStream;
 import java.util.Arrays;
 
-// === xdr source ============================================================
-
-//  typedef int TestArray[FOO];
-
-//  ===========================================================================
+/**
+ * TestArray's original definition in the XDR file is:
+ * <pre>
+ * typedef int TestArray[FOO];
+ * </pre>
+ */
 public class TestArray implements XdrElement {
   private Integer[] TestArray;
 

diff --git a/spec/output/generator_spec_java/const.x/TestArray2.java b/spec/output/generator_spec_java/const.x/TestArray2.java
@@ -11,11 +11,12 @@
 import java.io.ByteArrayOutputStream;
 import java.util.Arrays;
 
-// === xdr source ============================================================
-
-//  typedef int TestArray2<FOO>;
-
-//  ===========================================================================
+/**
+ * TestArray2's original definition in the XDR file is:
+ * <pre>
+ * typedef int TestArray2&lt;FOO&gt;;
+ * </pre>
+ */
 public class TestArray2 implements XdrElement {
   private Integer[] TestArray2;
 

diff --git a/spec/output/generator_spec_java/enum.x/Color.java b/spec/output/generator_spec_java/enum.x/Color.java
@@ -10,15 +10,16 @@
 import java.io.ByteArrayInputStream;
 import java.io.ByteArrayOutputStream;
 
-// === xdr source ============================================================
-
-//  enum Color {
-//      RED=0,  
-//      GREEN=1,  
-//      BLUE=2  
-//  };
-
-//  ===========================================================================
+/**
+ * Color's original definition in the XDR file is:
+ * <pre>
+ * enum Color {
+ *     RED=0,  
+ *     GREEN=1,  
+ *     BLUE=2  
+ * };
+ * </pre>
+ */
 public enum Color implements XdrElement {
   RED(0),
   GREEN(1),

diff --git a/spec/output/generator_spec_java/enum.x/Color2.java b/spec/output/generator_spec_java/enum.x/Color2.java
@@ -10,15 +10,16 @@
 import java.io.ByteArrayInputStream;
 import java.io.ByteArrayOutputStream;
 
-// === xdr source ============================================================
-
-//  enum Color2 {
-//      RED2=RED,  
-//      GREEN2=1,  
-//      BLUE2=2  
-//  };
-
-//  ===========================================================================
+/**
+ * Color2's original definition in the XDR file is:
+ * <pre>
+ * enum Color2 {
+ *     RED2=RED,  
+ *     GREEN2=1,  
+ *     BLUE2=2  
+ * };
+ * </pre>
+ */
 public enum Color2 implements XdrElement {
   RED2(0),
   GREEN2(1),

diff --git a/spec/output/generator_spec_java/enum.x/MessageType.java b/spec/output/generator_spec_java/enum.x/MessageType.java
@@ -10,33 +10,34 @@
 import java.io.ByteArrayInputStream;
 import java.io.ByteArrayOutputStream;
 
-// === xdr source ============================================================
-
-//  enum MessageType
-//  {
-//      ERROR_MSG,    
-//      HELLO,
-//      DONT_HAVE,
-//  
-//      GET_PEERS,   // gets a list of peers this guy knows about        
-//      PEERS,
-//  
-//      GET_TX_SET,  // gets a particular txset by hash        
-//      TX_SET,    
-//  
-//      GET_VALIDATIONS, // gets validations for a given ledger hash        
-//      VALIDATIONS,    
-//  
-//      TRANSACTION, //pass on a tx you have heard about        
-//      JSON_TRANSACTION,
-//  
-//      // FBA        
-//      GET_FBA_QUORUMSET,        
-//      FBA_QUORUMSET,    
-//      FBA_MESSAGE
-//  };
-
-//  ===========================================================================
+/**
+ * MessageType's original definition in the XDR file is:
+ * <pre>
+ * enum MessageType
+ * {
+ *     ERROR_MSG,    
+ *     HELLO,
+ *     DONT_HAVE,
+ * 
+ *     GET_PEERS,   // gets a list of peers this guy knows about        
+ *     PEERS,
+ * 
+ *     GET_TX_SET,  // gets a particular txset by hash        
+ *     TX_SET,    
+ * 
+ *     GET_VALIDATIONS, // gets validations for a given ledger hash        
+ *     VALIDATIONS,    
+ * 
+ *     TRANSACTION, //pass on a tx you have heard about        
+ *     JSON_TRANSACTION,
+ * 
+ *     // FBA        
+ *     GET_FBA_QUORUMSET,        
+ *     FBA_QUORUMSET,    
+ *     FBA_MESSAGE
+ * };
+ * </pre>
+ */
 public enum MessageType implements XdrElement {
   ERROR_MSG(0),
   HELLO(1),

diff --git a/spec/output/generator_spec_java/nesting.x/Foo.java b/spec/output/generator_spec_java/nesting.x/Foo.java
@@ -11,11 +11,12 @@
 import java.io.ByteArrayOutputStream;
 import java.util.Objects;
 
-// === xdr source ============================================================
-
-//  typedef int Foo;
-
-//  ===========================================================================
+/**
+ * Foo's original definition in the XDR file is:
+ * <pre>
+ * typedef int Foo;
+ * </pre>
+ */
 public class Foo implements XdrElement {
   private Integer Foo;
 

diff --git a/spec/output/generator_spec_java/nesting.x/MyUnion.java b/spec/output/generator_spec_java/nesting.x/MyUnion.java
@@ -11,26 +11,27 @@
 import java.io.ByteArrayOutputStream;
 import java.util.Objects;
 
-// === xdr source ============================================================
-
-//  union MyUnion switch (UnionKey type)
-//  {
-//      case ONE:
-//          struct {
-//              int someInt;
-//          } one;
-//  
-//      case TWO:
-//          struct {
-//              int someInt;
-//              Foo foo;
-//          } two;
-//  
-//      case OFFER:
-//          void;
-//  };
-
-//  ===========================================================================
+/**
+ * MyUnion's original definition in the XDR file is:
+ * <pre>
+ * union MyUnion switch (UnionKey type)
+ * {
+ *     case ONE:
+ *         struct {
+ *             int someInt;
+ *         } one;
+ * 
+ *     case TWO:
+ *         struct {
+ *             int someInt;
+ *             Foo foo;
+ *         } two;
+ * 
+ *     case OFFER:
+ *         void;
+ * };
+ * </pre>
+ */
 public class MyUnion implements XdrElement {
   public MyUnion () {}
   UnionKey type;
@@ -155,6 +156,14 @@ public static MyUnion fromXdrByteArray(byte[] xdr) throws IOException {
     return decode(xdrDataInputStream);
   }
 
+  /**
+   * MyUnionOne's original definition in the XDR file is:
+   * <pre>
+   * struct {
+   *             int someInt;
+   *         }
+   * </pre>
+   */
   public static class MyUnionOne implements XdrElement {
     public MyUnionOne () {}
     private Integer someInt;
@@ -228,6 +237,15 @@ public MyUnionOne build() {
     }
 
   }
+  /**
+   * MyUnionTwo's original definition in the XDR file is:
+   * <pre>
+   * struct {
+   *             int someInt;
+   *             Foo foo;
+   *         }
+   * </pre>
+   */
   public static class MyUnionTwo implements XdrElement {
     public MyUnionTwo () {}
     private Integer someInt;

diff --git a/spec/output/generator_spec_java/nesting.x/UnionKey.java b/spec/output/generator_spec_java/nesting.x/UnionKey.java
@@ -10,15 +10,16 @@
 import java.io.ByteArrayInputStream;
 import java.io.ByteArrayOutputStream;
 
-// === xdr source ============================================================
-
-//  enum UnionKey {
-//    ONE = 1,
-//    TWO = 2,
-//    OFFER = 3
-//  };
-
-//  ===========================================================================
+/**
+ * UnionKey's original definition in the XDR file is:
+ * <pre>
+ * enum UnionKey {
+ *   ONE = 1,
+ *   TWO = 2,
+ *   OFFER = 3
+ * };
+ * </pre>
+ */
 public enum UnionKey implements XdrElement {
   ONE(1),
   TWO(2),

diff --git a/spec/output/generator_spec_java/optional.x/Arr.java b/spec/output/generator_spec_java/optional.x/Arr.java
@@ -11,11 +11,12 @@
 import java.io.ByteArrayOutputStream;
 import java.util.Arrays;
 
-// === xdr source ============================================================
-
-//  typedef int Arr[2];
-
-//  ===========================================================================
+/**
+ * Arr's original definition in the XDR file is:
+ * <pre>
+ * typedef int Arr[2];
+ * </pre>
+ */
 public class Arr implements XdrElement {
   private Integer[] Arr;
 

diff --git a/spec/output/generator_spec_java/optional.x/HasOptions.java b/spec/output/generator_spec_java/optional.x/HasOptions.java
@@ -11,16 +11,17 @@
 import java.io.ByteArrayOutputStream;
 import java.util.Objects;
 
-// === xdr source ============================================================
-
-//  struct HasOptions
-//  {
-//    int* firstOption;
-//    int *secondOption;
-//    Arr *thirdOption;
-//  };
-
-//  ===========================================================================
+/**
+ * HasOptions's original definition in the XDR file is:
+ * <pre>
+ * struct HasOptions
+ * {
+ *   int&#42; firstOption;
+ *   int &#42;secondOption;
+ *   Arr &#42;thirdOption;
+ * };
+ * </pre>
+ */
 public class HasOptions implements XdrElement {
   public HasOptions () {}
   private Integer firstOption;