More Ruby docs

Author: kddnewton

lib/prism/ffi.rb

@@ -9,7 +9,7 @@
 module Prism
   BACKEND = :FFI
 
-  module LibRubyParser
+  module LibRubyParser # :nodoc:
     extend FFI::Library
 
     # Define the library that we will be pulling functions from. Note that this
@@ -95,7 +95,7 @@ def self.load_exported_functions_from(header, *functions)
 
     # This object represents a pm_buffer_t. We only use it as an opaque pointer,
     # so it doesn't need to know the fields of pm_buffer_t.
-    class PrismBuffer
+    class PrismBuffer # :nodoc:
       SIZEOF = LibRubyParser.pm_buffer_sizeof
 
       attr_reader :pointer
@@ -133,7 +133,7 @@ def self.with(&block)
 
     # This object represents a pm_string_t. We only use it as an opaque pointer,
     # so it doesn't have to be an FFI::Struct.
-    class PrismString
+    class PrismString # :nodoc:
       SIZEOF = LibRubyParser.pm_string_sizeof
 
       attr_reader :pointer
@@ -168,6 +168,7 @@ def self.with(filepath, &block)
       end
     end
 
+    # Dump the given source into a serialized format.
     def self.dump_internal(source, source_size, filepath)
       PrismBuffer.with do |buffer|
         metadata = [filepath.bytesize, filepath.b, 0].pack("LA*L") if filepath

lib/prism/lex_compat.rb

@@ -8,7 +8,7 @@ module Prism
   # of cases, this is a one-to-one mapping of the token type. Everything else
   # generally lines up. However, there are a few cases that require special
   # handling.
-  class LexCompat
+  class LexCompat # :nodoc:
     # This is a mapping of prism token types to Ripper token types. This is a
     # many-to-one mapping because we split up our token types, whereas Ripper
     # tends to group them.
@@ -184,18 +184,22 @@ class LexCompat
     # However, we add a couple of convenience methods onto them to make them a
     # little easier to work with. We delegate all other methods to the array.
     class Token < SimpleDelegator
+      # The location of the token in the source.
       def location
         self[0]
       end
 
+      # The type of the token.
       def event
         self[1]
       end
 
+      # The slice of the source that this token represents.
       def value
         self[2]
       end
 
+      # The state of the lexer when this token was produced.
       def state
         self[3]
       end
@@ -204,15 +208,15 @@ def state
     # Ripper doesn't include the rest of the token in the event, so we need to
     # trim it down to just the content on the first line when comparing.
     class EndContentToken < Token
-      def ==(other)
+      def ==(other) # :nodoc:
         [self[0], self[1], self[2][0..self[2].index("\n")], self[3]] == other
       end
     end
 
     # Tokens where state should be ignored
     # used for :on_comment, :on_heredoc_end, :on_embexpr_end
     class IgnoreStateToken < Token
-      def ==(other)
+      def ==(other) # :nodoc:
         self[0...-1] == other[0...-1]
       end
     end
@@ -222,7 +226,7 @@ def ==(other)
     # through named captures in regular expressions). In that case we don't
     # compare the state.
     class IdentToken < Token
-      def ==(other)
+      def ==(other) # :nodoc:
         (self[0...-1] == other[0...-1]) && (
           (other[3] == Ripper::EXPR_LABEL | Ripper::EXPR_END) ||
           (other[3] & Ripper::EXPR_ARG_ANY != 0)
@@ -233,7 +237,7 @@ def ==(other)
     # Ignored newlines can occasionally have a LABEL state attached to them, so
     # we compare the state differently here.
     class IgnoredNewlineToken < Token
-      def ==(other)
+      def ==(other) # :nodoc:
         return false unless self[0...-1] == other[0...-1]
 
         if self[4] == Ripper::EXPR_ARG | Ripper::EXPR_LABELED
@@ -253,7 +257,7 @@ def ==(other)
     # more accurately, so we need to allow comparing against both END and
     # END|LABEL.
     class ParamToken < Token
-      def ==(other)
+      def ==(other) # :nodoc:
         (self[0...-1] == other[0...-1]) && (
           (other[3] == Ripper::EXPR_END) ||
           (other[3] == Ripper::EXPR_END | Ripper::EXPR_LABEL)
@@ -264,12 +268,12 @@ def ==(other)
     # A heredoc in this case is a list of tokens that belong to the body of the
     # heredoc that should be appended onto the list of tokens when the heredoc
     # closes.
-    module Heredoc
+    module Heredoc # :nodoc:
       # Heredocs that are no dash or tilde heredocs are just a list of tokens.
       # We need to keep them around so that we can insert them in the correct
       # order back into the token stream and set the state of the last token to
       # the state that the heredoc was opened in.
-      class PlainHeredoc
+      class PlainHeredoc # :nodoc:
         attr_reader :tokens
 
         def initialize
@@ -288,7 +292,7 @@ def to_a
       # Dash heredocs are a little more complicated. They are a list of tokens
       # that need to be split on "\\\n" to mimic Ripper's behavior. We also need
       # to keep track of the state that the heredoc was opened in.
-      class DashHeredoc
+      class DashHeredoc # :nodoc:
         attr_reader :split, :tokens
 
         def initialize(split)
@@ -347,7 +351,7 @@ def to_a
       # insert them into the stream in the correct order. As such, we can do
       # some extra manipulation on the tokens to make them match Ripper's
       # output by mirroring the dedent logic that Ripper uses.
-      class DedentingHeredoc
+      class DedentingHeredoc # :nodoc:
         TAB_WIDTH = 8
 
         attr_reader :tokens, :dedent_next, :dedent, :embexpr_balance
@@ -588,6 +592,8 @@ def self.build(opening)
       end
     end
 
+    private_constant :Heredoc
+
     attr_reader :source, :filepath
 
     def initialize(source, filepath = "")
@@ -829,9 +835,11 @@ def result
     end
   end
 
+  private_constant :LexCompat
+
   # This is a class that wraps the Ripper lexer to produce almost exactly the
   # same tokens.
-  class LexRipper
+  class LexRipper # :nodoc:
     attr_reader :source
 
     def initialize(source)
@@ -869,4 +877,6 @@ def result
       results
     end
   end
+
+  private_constant :LexRipper
 end

lib/prism/node_ext.rb

@@ -3,7 +3,7 @@
 # Here we are reopening the prism module to provide methods on nodes that aren't
 # templated and are meant as convenience methods.
 module Prism
-  module RegularExpressionOptions
+  module RegularExpressionOptions # :nodoc:
     # Returns a numeric value that represents the flags that were used to create
     # the regular expression.
     def options

lib/prism/node_inspector.rb

@@ -3,7 +3,7 @@
 module Prism
   # This object is responsible for generating the output for the inspect method
   # implementations of child nodes.
-  class NodeInspector
+  class NodeInspector # :nodoc:
     attr_reader :prefix, :output
 
     def initialize(prefix = "")

lib/prism/pack.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Prism
+  # A parser for the pack template language.
   module Pack
     %i[
       SPACE
@@ -54,6 +55,7 @@ module Pack
       const_set(const, const)
     end
 
+    # A directive in the pack template language.
     class Directive
       attr_reader :version, :variant, :source, :type, :signed, :endian, :size, :length_type, :length
 
@@ -70,37 +72,37 @@ def initialize(version, variant, source, type, signed, endian, size, length_type
       end
 
       ENDIAN_DESCRIPTIONS = {
-        AGNOSTIC_ENDIAN: 'agnostic',
-        LITTLE_ENDIAN: 'little-endian (VAX)',
-        BIG_ENDIAN: 'big-endian (network)',
-        NATIVE_ENDIAN: 'native-endian',
-        ENDIAN_NA: 'n/a'
+        AGNOSTIC_ENDIAN: "agnostic",
+        LITTLE_ENDIAN: "little-endian (VAX)",
+        BIG_ENDIAN: "big-endian (network)",
+        NATIVE_ENDIAN: "native-endian",
+        ENDIAN_NA: "n/a"
       }
 
       SIGNED_DESCRIPTIONS = {
-        UNSIGNED: 'unsigned',
-        SIGNED: 'signed',
-        SIGNED_NA: 'n/a'
+        UNSIGNED: "unsigned",
+        SIGNED: "signed",
+        SIGNED_NA: "n/a"
       }
 
       SIZE_DESCRIPTIONS = {
-        SIZE_SHORT: 'short',
-        SIZE_INT: 'int-width',
-        SIZE_LONG: 'long',
-        SIZE_LONG_LONG: 'long long',
-        SIZE_8: '8-bit',
-        SIZE_16: '16-bit',
-        SIZE_32: '32-bit',
-        SIZE_64: '64-bit',
-        SIZE_P: 'pointer-width'
+        SIZE_SHORT: "short",
+        SIZE_INT: "int-width",
+        SIZE_LONG: "long",
+        SIZE_LONG_LONG: "long long",
+        SIZE_8: "8-bit",
+        SIZE_16: "16-bit",
+        SIZE_32: "32-bit",
+        SIZE_64: "64-bit",
+        SIZE_P: "pointer-width"
       }
 
       def describe
         case type
         when SPACE
-          'whitespace'
+          "whitespace"
         when COMMENT
-          'comment'
+          "comment"
         when INTEGER
           if size == SIZE_8
             base = "#{SIGNED_DESCRIPTIONS[signed]} #{SIZE_DESCRIPTIONS[size]} integer"
@@ -115,50 +117,51 @@ def describe
               base
             end
           when LENGTH_MAX
-            base + ', as many as possible'
+            base + ", as many as possible"
           end
         when UTF8
-          'UTF-8 character'
+          "UTF-8 character"
         when BER
-          'BER-compressed integer'
+          "BER-compressed integer"
         when FLOAT
           "#{SIZE_DESCRIPTIONS[size]} #{ENDIAN_DESCRIPTIONS[endian]} float"
         when STRING_SPACE_PADDED
-          'arbitrary binary string (space padded)'
+          "arbitrary binary string (space padded)"
         when STRING_NULL_PADDED
-          'arbitrary binary string (null padded, count is width)'
+          "arbitrary binary string (null padded, count is width)"
         when STRING_NULL_TERMINATED
-          'arbitrary binary string (null padded, count is width), except that null is added with *'
+          "arbitrary binary string (null padded, count is width), except that null is added with *"
         when STRING_MSB
-          'bit string (MSB first)'
+          "bit string (MSB first)"
         when STRING_LSB
-          'bit string (LSB first)'
+          "bit string (LSB first)"
         when STRING_HEX_HIGH
-          'hex string (high nibble first)'
+          "hex string (high nibble first)"
         when STRING_HEX_LOW
-          'hex string (low nibble first)'
+          "hex string (low nibble first)"
         when STRING_UU
-          'UU-encoded string'
+          "UU-encoded string"
         when STRING_MIME
-          'quoted printable, MIME encoding'
+          "quoted printable, MIME encoding"
         when STRING_BASE64
-          'base64 encoded string'
+          "base64 encoded string"
         when STRING_FIXED
-          'pointer to a structure (fixed-length string)'
+          "pointer to a structure (fixed-length string)"
         when STRING_POINTER
-          'pointer to a null-terminated string'
+          "pointer to a null-terminated string"
         when MOVE
-          'move to absolute position'
+          "move to absolute position"
         when BACK
-          'back up a byte'
+          "back up a byte"
         when NULL
-          'null byte'
+          "null byte"
         else
           raise
         end
       end
     end
 
+    # A class used to describe what a pack template does.
     class Format
       attr_reader :directives, :encoding
 
@@ -178,7 +181,7 @@ def describe
           "  #{source.ljust(source_width)}  #{directive.describe}"
         end
 
-        (['Directives:'] + directive_lines + ['Encoding:', "  #{encoding}"]).join("\n")
+        (["Directives:"] + directive_lines + ["Encoding:", "  #{encoding}"]).join("\n")
       end
     end
   end

lib/prism/parse_result.rb

@@ -58,6 +58,8 @@ def column(value)
 
     private
 
+    # Find all of the newlines in the source code and return their byte offsets
+    # from the start of the string an array.
     def compute_offsets(code)
       offsets = [0]
       code.b.scan("\n") { offsets << $~.end(0) }

lib/prism/parse_result/comments.rb

@@ -19,7 +19,7 @@ class ParseResult
     class Comments
       # A target for attaching comments that is based on a specific node's
       # location.
-      class NodeTarget
+      class NodeTarget # :nodoc:
         attr_reader :node
 
         def initialize(node)
@@ -46,7 +46,7 @@ def <<(comment)
 
       # A target for attaching comments that is based on a location field on a
       # node. For example, the `end` token of a ClassNode.
-      class LocationTarget
+      class LocationTarget # :nodoc:
         attr_reader :location
 
         def initialize(location)
@@ -70,12 +70,17 @@ def <<(comment)
         end
       end
 
+      # The parse result that we are attaching comments to.
       attr_reader :parse_result
 
+      # Create a new Comments object that will attach comments to the given
+      # parse result.
       def initialize(parse_result)
         @parse_result = parse_result
       end
 
+      # Attach the comments to their respective locations in the tree by
+      # mutating the parse result.
       def attach!
         parse_result.comments.each do |comment|
           preceding, enclosing, following = nearest_targets(parse_result.value, comment)