Merge pull request ruby#2494 from ruby/javadoc

Java documentation

.github/workflows/documentation.yml

@@ -0,0 +1,35 @@
+name: Documentation
+
+concurrency:
+  group: "${{github.workflow}}-${{github.ref}}"
+  cancel-in-progress: true
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: "3.2"
+        bundler-cache: true
+    - name: Install doxygen and dependencies
+      run: |
+        sudo apt-get update
+        sudo apt-get install doxygen graphviz
+    - name: Generate the templates
+      run: bundle exec rake templates
+    - name: Check ruby coverage
+      run: bundle exec rake rdoc:coverage
+    - name: Check C coverage
+      run: doxygen Doxyfile
+    - name: Check Java coverage
+      run: javadoc -Xdoclint:all,-missing -d ../doc/java -subpackages *
+      working-directory: java

.github/workflows/github-pages.yml

@@ -46,6 +46,9 @@ jobs:
         run: bundle exec rake rdoc
       - name: Build with Doxygen
         run: doxygen Doxyfile
+      - name: Build with JavaDoc
+        run: javadoc -Xdoclint:all,-missing -d ../doc/java -subpackages *
+        working-directory: java
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:

.github/workflows/main.yml

@@ -313,23 +313,3 @@ jobs:
       run: |
         scan-build bundle exec rake compile 2>&1 | tee /tmp/scan_build_output.log
         grep -q 'scan-build: No bugs found.' /tmp/scan_build_output.log
-
-  documentation:
-    runs-on: ubuntu-latest
-    steps:
-    - uses: actions/checkout@v4
-    - name: Set up Ruby
-      uses: ruby/setup-ruby@v1
-      with:
-        ruby-version: "3.2"
-        bundler-cache: true
-    - name: Install doxygen and dependencies
-      run: |
-        sudo apt-get update
-        sudo apt-get install doxygen graphviz
-    - name: Generate the templates
-      run: bundle exec rake templates
-    - name: Check ruby coverage
-      run: bundle exec rake rdoc:coverage
-    - name: Check C coverage
-      run: doxygen Doxyfile

.gitignore

@@ -4,6 +4,7 @@
 /_yardoc/
 /coverage/
 /doc/c/
+/doc/java/
 /doc/rb/
 /pkg/
 /spec/reports/

doc/index.css

@@ -23,13 +23,14 @@ h1 {
 main {
   display: grid;
   grid-template-rows: 1fr 1fr;
+  grid-template-columns: 1fr 1fr;
   height: 36vh;
-  margin: 2vh 30vw;
+  margin: 2vh 20vw;
 }
 
 @media only screen and (max-width: 1200px) {
   main {
-    margin: 2vh 20vw;
+    margin: 2vh 10vw;
   }
 }
 
@@ -51,6 +52,10 @@ main {
   vertical-align: middle;
 }
 
+.reference:first-child {
+  grid-column: span 2;
+}
+
 .reference > img {
   height: 10vh;
   width: 10vh;

doc/index.html

@@ -14,13 +14,17 @@
       <h1>Prism Ruby parser</h1>
     </header>
     <main>
+      <a class="reference" href="c/index.html">
+        <img src="images/c.svg" alt="C">
+        <h2>C reference</h2>
+      </a>
       <a class="reference" href="rb/index.html">
         <img src="images/ruby.svg" alt="Ruby">
         <h2>Ruby reference</h2>
       </a>
-      <a class="reference" href="c/index.html">
-        <img src="images/c.svg" alt="C">
-        <h2>C reference</h2>
+      <a class="reference" href="java/index.html">
+        <img src="images/java.png" alt="Java">
+        <h2>Java reference</h2>
       </a>
     </main>
     <footer>

templates/java/org/prism/AbstractNodeVisitor.java.erb

@@ -6,6 +6,12 @@ public abstract class AbstractNodeVisitor<T> {
     protected abstract T defaultVisit(Nodes.Node node);
 
     <%- nodes.each do |node| -%>
+    /**
+     * Visit a <%= node.name %> node.
+     *
+     * @param node The node to visit.
+     * @return The result of visiting the node.
+     */
     public T visit<%= node.name -%>(Nodes.<%= node.name -%> node) {
         return defaultVisit(node);
     }

templates/java/org/prism/Nodes.java.erb

@@ -132,7 +132,7 @@ public abstract class Nodes {
     <%- flags.each do |group| -%>
 
     /**
-     * <%= group.comment %>
+     * <%= Prism::JavaDoc.escape(group.comment) %>
      */
     public static final class <%= group.name %> implements Comparable<<%= group.name %>> {
         <%- group.values.each_with_index do |value, index| -%>
@@ -184,9 +184,11 @@ public abstract class Nodes {
     <%- nodes.each do |node| -%>
 
     /**
-    <%- node.each_comment_line do |line| -%>
+     * <pre>
+    <%- node.each_comment_java_line do |line| -%>
      *<%= line %>
     <%- end -%>
+     * </pre>
      */
     public static final class <%= node.name -%> extends Node {
         <%- if node.needs_serialized_length? -%>
@@ -196,7 +198,7 @@ public abstract class Nodes {
         <%- if field.comment -%>
         /**
          * <pre>
-        <%- field.each_comment_line do |line| -%>
+        <%- field.each_comment_java_line do |line| -%>
          *<%= line %>
         <%- end -%>
          * </pre>

templates/template.rb

@@ -10,6 +10,39 @@ module Prism
   JAVA_BACKEND = ENV["PRISM_JAVA_BACKEND"] || "truffleruby"
   JAVA_STRING_TYPE = JAVA_BACKEND == "jruby" ? "org.jruby.RubySymbol" : "String"
 
+  # This module contains methods for escaping characters in JavaDoc comments.
+  module JavaDoc
+    ESCAPES = {
+      "'" => "'",
+      "\"" => """,
+      "@" => "@",
+      "&" => "&",
+      "<" => "&lt;",
+      ">" => "&gt;"
+    }.freeze
+
+    def self.escape(value)
+      value.gsub(/['&"<>@]/, ESCAPES)
+    end
+  end
+
+  # A comment attached to a field or node.
+  class Comment
+    attr_reader :value
+
+    def initialize(value)
+      @value = value
+    end
+
+    def each_line(&block)
+      value.each_line { |line| yield line.prepend(" ").rstrip }
+    end
+
+    def each_java_line(&block)
+      Comment.new(JavaDoc.escape(value)).each_line(&block)
+    end
+  end
+
   # This represents a field on a node. It contains all of the necessary
   # information to template out the code for that field.
   class Field
@@ -21,8 +54,12 @@ def initialize(name:, comment: nil, **options)
       @options = options
     end
 
-    def each_comment_line
-      comment.each_line { |line| yield line.prepend(" ").rstrip } if comment
+    def each_comment_line(&block)
+      Comment.new(comment).each_line(&block) if comment
+    end
+
+    def each_comment_java_line(&block)
+      Comment.new(comment).each_java_line(&block) if comment
     end
 
     def semantic_field?
@@ -317,8 +354,12 @@ def initialize(config)
       @comment = config.fetch("comment")
     end
 
-    def each_comment_line
-      comment.each_line { |line| yield line.prepend(" ").rstrip }
+    def each_comment_line(&block)
+      Comment.new(comment).each_line(&block)
+    end
+
+    def each_comment_java_line(&block)
+      Comment.new(comment).each_java_line(&block)
     end
 
     def semantic_fields