Merge pull request #1754 from ruby/docs

Documentation updates

.github/workflows/main.yml

@@ -288,3 +288,23 @@ 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@v3
+    - 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

@@ -3,7 +3,8 @@
 /.yardoc
 /_yardoc/
 /coverage/
-/doc/
+/doc/c/
+/doc/rb/
 /pkg/
 /spec/reports/
 /top-100-gems/

Doxyfile

@@ -0,0 +1,32 @@
+# Doxyfile 1.9.5
+
+# This file describes the settings to be used by the documentation system
+# doxygen (www.doxygen.org) for a project.
+#
+# All text after a double hash (##) is considered a comment and is placed in
+# front of the TAG it is preceding.
+#
+# All text after a single hash (#) is considered a comment and will be ignored.
+# The format is:
+# TAG = value [value, ...]
+# For lists, items can also be appended using:
+# TAG += value [value, ...]
+# Values that contain spaces should be placed between quotes (\" \").
+#
+# Note:
+#
+# Use doxygen to compare the used configuration file with the template
+# configuration file:
+# doxygen -x [configFile]
+
+PROJECT_NAME           = "Prism Ruby parser"
+OUTPUT_DIRECTORY       = doc
+JAVADOC_AUTOBRIEF      = YES
+OPTIMIZE_OUTPUT_FOR_C  = YES
+INPUT                  = src src/enc src/util include include/prism include/prism/enc include/prism/util
+HTML_OUTPUT            = c
+SORT_MEMBER_DOCS       = NO
+GENERATE_LATEX         = NO
+WARN_NO_PARAMDOC       = YES
+WARN_AS_ERROR          = FAIL_ON_WARNINGS
+DOT_GRAPH_MAX_NODES    = 200

README.md

@@ -1,6 +1,6 @@
 <h1 align="center">Prism Ruby parser</h1>
 <div align="center">
-  <img alt="Prism Ruby parser" height="256px" src="https://github.com/ruby/prism/blob/main/docs/prism.png?raw=true">
+  <img alt="Prism Ruby parser" height="256px" src="https://github.com/ruby/prism/blob/main/doc/images/prism.png?raw=true">
 </div>
 
 This is a parser for the Ruby programming language. It is designed to be portable, error tolerant, and maintainable. It is written in C99 and has no dependencies. It is currently being integrated into [CRuby](https://github.com/ruby/ruby), [JRuby](https://github.com/jruby/jruby), [TruffleRuby](https://github.com/oracle/truffleruby), [Sorbet](https://github.com/sorbet/sorbet), and [Syntax Tree](https://github.com/ruby-syntax-tree/syntax_tree).

config.yml

@@ -59,11 +59,11 @@ tokens:
   - name: CONSTANT
     comment: "a constant"
   - name: DOT
-    comment: "."
+    comment: "the . call operator"
   - name: DOT_DOT
-    comment: ".."
+    comment: "the .. range operator"
   - name: DOT_DOT_DOT
-    comment: "..."
+    comment: "the ... range operator or forwarding parameter"
   - name: EMBDOC_BEGIN
     comment: "=begin"
   - name: EMBDOC_END
@@ -311,9 +311,9 @@ tokens:
   - name: UCOLON_COLON
     comment: "unary ::"
   - name: UDOT_DOT
-    comment: "unary .."
+    comment: "unary .. operator"
   - name: UDOT_DOT_DOT
-    comment: "unary ..."
+    comment: "unary ... operator"
   - name: UMINUS
     comment: "-@"
   - name: UMINUS_NUM
@@ -333,12 +333,14 @@ flags:
     values:
       - name: KEYWORD_SPLAT
         comment: "if arguments contain keyword splat"
+    comment: Flags for arguments nodes.
   - name: CallNodeFlags
     values:
       - name: SAFE_NAVIGATION
         comment: "&. operator"
       - name: VARIABLE_CALL
         comment: "a call that could have been a local variable"
+    comment: Flags for call nodes.
   - name: IntegerBaseFlags
     values:
       - name: BINARY
@@ -349,14 +351,17 @@ flags:
         comment: "0d or no prefix"
       - name: HEXADECIMAL
         comment: "0x prefix"
+    comment: Flags for integer nodes that correspond to the base of the integer.
   - name: LoopFlags
     values:
       - name: BEGIN_MODIFIER
         comment: "a loop after a begin statement, so the body is executed first before the condition"
+    comment: Flags for while and until loop nodes.
   - name: RangeFlags
     values:
       - name: EXCLUDE_END
         comment: "... operator"
+    comment: Flags for range and flip-flop nodes.
   - name: RegularExpressionFlags
     values:
       - name: IGNORE_CASE
@@ -375,10 +380,12 @@ flags:
         comment: "s - forces the Windows-31J encoding"
       - name: UTF_8
         comment: "u - forces the UTF-8 encoding"
+    comment: Flags for regular expression and match last line nodes.
   - name: StringFlags
     values:
       - name: FROZEN
         comment: "frozen by virtue of a `frozen_string_literal` comment"
+    comment: Flags for string nodes.
 nodes:
   - name: AliasGlobalVariableNode
     fields:
@@ -777,10 +784,10 @@ nodes:
     comment: |
       Represents the use of a case statement.
 
-      case true
-      ^^^^^^^^^
-      when false
-      end
+          case true
+          when false
+          end
+          ^^^^^^^^^^
   - name: ClassNode
     fields:
       - name: locals
@@ -818,7 +825,7 @@ nodes:
       Represents the use of the `&&=` operator for assignment to a class variable.
 
           @@target &&= value
-          ^^^^^^^^^^^^^^^^
+          ^^^^^^^^^^^^^^^^^^
   - name: ClassVariableOperatorWriteNode
     fields:
       - name: name
@@ -1183,13 +1190,13 @@ nodes:
       Represents a find pattern in pattern matching.
 
           foo in *bar, baz, *qux
-          ^^^^^^^^^^^^^^^^^^^^^^
+                 ^^^^^^^^^^^^^^^
 
           foo in [*bar, baz, *qux]
-          ^^^^^^^^^^^^^^^^^^^^^^^^
+                 ^^^^^^^^^^^^^^^^^
 
           foo in Foo(*bar, baz, *qux)
-          ^^^^^^^^^^^^^^^^^^^^^^^^^^^
+                 ^^^^^^^^^^^^^^^^^^^^
   - name: FlipFlopNode
     fields:
       - name: left
@@ -1240,7 +1247,7 @@ nodes:
 
           def foo(...)
             bar(...)
-            ^^^^^^^^
+                ^^^
           end
   - name: ForwardingParameterNode
     comment: |
@@ -2237,8 +2244,8 @@ nodes:
 
           begin
           rescue Foo, *splat, Bar => ex
-          ^^^^^^
             foo
+          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
           end
 
       `Foo, *splat, Bar` are in the `exceptions` field.