rdoc 3.12.2 → 4.0.0.preview2

data/lib/rdoc/parser/markdown.rb

@@ -0,0 +1,23 @@
+##
+# Parse a Markdown format file.  The parsed RDoc::Markup::Document is attached
+# as a file comment.
+
+class RDoc::Parser::Markdown < RDoc::Parser
+
+  include RDoc::Parser::Text
+
+  parse_files_matching(/\.(md|markdown)(?:\.[^.]+)?$/)
+
+  ##
+  # Creates an Markdown-format TopLevel for the given file.
+
+  def scan
+    comment = RDoc::Comment.new @content, @top_level
+    comment.format = 'markdown'
+
+    @top_level.comment = comment
+  end
+
+end
+
+

data/lib/rdoc/parser/ruby.rb

@@ -94,7 +94,7 @@ $TOKEN_DEBUG ||= nil
 # You can force the name of a method using the :method: directive:
 #
 #   ##
-#   # :method: woo_hoo!
+#   # :method: some_method!
 #
 # By default, meta-methods are instance methods.  To indicate that a method is
 # a singleton method instead use the :singleton-method: directive:
@@ -105,7 +105,7 @@ $TOKEN_DEBUG ||= nil
 # You can also use the :singleton-method: directive with a name:
 #
 #   ##
-#   # :singleton-method: woo_hoo!
+#   # :singleton-method: some_method!
 #
 # Additionally you can mark a method as an attribute by
 # using :attr:, :attr_reader:, :attr_writer: or :attr_accessor:.  Just like
@@ -240,7 +240,7 @@ class RDoc::Parser::Ruby < RDoc::Parser
   # with :: separated named) and return the ultimate name, the associated
   # container, and the given name (with the ::).
 
-  def get_class_or_module(container)
+  def get_class_or_module container
     skip_tkspace
     name_t = get_tk
     given_name = ''
@@ -259,14 +259,18 @@ class RDoc::Parser::Ruby < RDoc::Parser
     while TkCOLON2 === peek_tk do
       prev_container = container
       container = container.find_module_named name_t.name
-      unless container then
-        container = prev_container.add_module RDoc::NormalModule, name_t.name
-      end
+      container ||= prev_container.add_module RDoc::NormalModule, name_t.name
+
+      container.ignore unless prev_container.document_children
+
       get_tk
+      skip_tkspace false
       name_t = get_tk
       given_name << '::' << name_t.name
     end
+
     skip_tkspace false
+
     return [container, name_t, given_name]
   end
 
@@ -275,9 +279,10 @@ class RDoc::Parser::Ruby < RDoc::Parser
 
   def get_class_specification
     tk = get_tk
-    return "self" if TkSELF === tk
+    return 'self' if TkSELF === tk
+    return ''     if TkGVAR === tk
 
-    res = ""
+    res = ''
     while TkCOLON2 === tk or TkCOLON3 === tk or TkCONSTANT === tk do
       res += tk.name
       tk = get_tk
@@ -587,6 +592,11 @@ class RDoc::Parser::Ruby < RDoc::Parser
       name = name_t.name
       superclass = '::Object'
 
+      if given_name =~ /^::/ then
+        declaration_context = @top_level
+        given_name = $'
+      end
+
       if TkLT === peek_tk then
         get_tk
         skip_tkspace
@@ -611,17 +621,25 @@ class RDoc::Parser::Ruby < RDoc::Parser
       parse_statements cls
     when TkLSHFT
       case name = get_class_specification
-      when "self", container.name
+      when 'self', container.name
         parse_statements container, SINGLE
       else
-        other = RDoc::TopLevel.find_class_named name
+        other = @store.find_class_named name
 
         unless other then
+          if name =~ /^::/ then
+            name = $'
+            container = @top_level
+          end
+
           other = container.add_module RDoc::NormalModule, name
           other.record_location @top_level
           other.offset  = offset
           other.line    = line_no
 
+          # class << $gvar
+          other.ignore if name.empty?
+
           other.add_comment comment, @top_level
         end
 
@@ -701,7 +719,7 @@ class RDoc::Parser::Ruby < RDoc::Parser
 
         if nest <= 0 and TkNL === peek_tk then
           mod = if rhs_name =~ /^::/ then
-                  RDoc::TopLevel.find_class_or_module rhs_name
+                  @store.find_class_or_module rhs_name
                 else
                   container.find_module_named rhs_name
                 end
@@ -767,7 +785,7 @@ class RDoc::Parser::Ruby < RDoc::Parser
       indent.set_text " " * column
 
       position_comment = TkCOMMENT.new 0, line_no, 1
-      position_comment.set_text "# File #{@top_level.absolute_name}, line #{line_no}"
+      position_comment.set_text "# File #{@top_level.relative_name}, line #{line_no}"
       meth.add_tokens [position_comment, NEWLINE_TOKEN, indent]
 
       meth.params = ''
@@ -825,7 +843,7 @@ class RDoc::Parser::Ruby < RDoc::Parser
     indent.set_text " " * offset
 
     position_comment = TkCOMMENT.new 0, line_no, 1
-    position_comment.set_text "# File #{@top_level.absolute_name}, line #{line_no}"
+    position_comment.set_text "# File #{@top_level.relative_name}, line #{line_no}"
     meth.add_tokens [position_comment, NEWLINE_TOKEN, indent]
 
     meth.call_seq = signature
@@ -861,6 +879,26 @@ class RDoc::Parser::Ruby < RDoc::Parser
     end
   end
 
+  ##
+  # Parses an +extend+ in +context+ with +comment+
+
+  def parse_extend context, comment
+    loop do
+      skip_tkspace_comment
+
+      name = get_constant_with_optional_parens
+
+      unless name.empty? then
+        incl = context.add_extend RDoc::Extend.new(name, comment)
+        incl.record_location @top_level
+      end
+
+      return unless TkCOMMA === peek_tk
+
+      get_tk
+    end
+  end
+
   ##
   # Parses a meta-programmed attribute and creates an RDoc::Attr.
   #
@@ -924,6 +962,8 @@ class RDoc::Parser::Ruby < RDoc::Parser
         @stats.add_attribute att
       end
     end
+
+    att
   end
 
   ##
@@ -975,7 +1015,7 @@ class RDoc::Parser::Ruby < RDoc::Parser
     indent.set_text " " * column
 
     position_comment = TkCOMMENT.new 0, line_no, 1
-    position_comment.value = "# File #{@top_level.absolute_name}, line #{line_no}"
+    position_comment.value = "# File #{@top_level.relative_name}, line #{line_no}"
     meth.add_tokens [position_comment, NEWLINE_TOKEN, indent]
     meth.add_tokens @token_stream
 
@@ -998,7 +1038,6 @@ class RDoc::Parser::Ruby < RDoc::Parser
         when TkSPACE then
           # expression continues
         when TkDO then
-          unget_tk tk
           parse_statements container, single, meth
           break
         else
@@ -1010,6 +1049,8 @@ class RDoc::Parser::Ruby < RDoc::Parser
     meth.comment = comment
 
     @stats.add_method meth
+
+    meth
   end
 
   ##
@@ -1035,15 +1076,23 @@ class RDoc::Parser::Ruby < RDoc::Parser
       meth = nil
       added_container = false
 
-      dot = get_tk
-      if TkDOT === dot or TkCOLON2 === dot then
+      case dot = get_tk
+      when TkDOT, TkCOLON2 then
         @scanner.instance_eval do @lex_state = EXPR_FNAME end
         skip_tkspace
         name_t2 = get_tk
 
         case name_t
         when TkSELF, TkMOD then
-          name = name_t2.name
+          name = case name_t2
+                 # NOTE: work around '[' being consumed early and not being
+                 # re-tokenized as a TkAREF
+                 when TkfLBRACK then
+                   get_tk
+                   '[]'
+                 else
+                   name_t2.name
+                 end
         when TkCONSTANT then
           name = name_t2.name
           prev_container = container
@@ -1072,11 +1121,12 @@ class RDoc::Parser::Ruby < RDoc::Parser
         when TkIDENTIFIER, TkIVAR, TkGVAR then
           dummy = RDoc::Context.new
           dummy.parent = container
+          dummy.store  = container.store
           skip_method dummy
           return
         when TkTRUE, TkFALSE, TkNIL then
           klass_name = "#{name_t.name.capitalize}Class"
-          container = RDoc::TopLevel.find_class_named klass_name
+          container = @store.find_class_named klass_name
           container ||= @top_level.add_class RDoc::NormalClass, klass_name
 
           name = name_t2.name
@@ -1121,7 +1171,7 @@ class RDoc::Parser::Ruby < RDoc::Parser
     indent.set_text " " * column
 
     token = TkCOMMENT.new 0, line_no, 1
-    token.set_text "# File #{@top_level.absolute_name}, line #{line_no}"
+    token.set_text "# File #{@top_level.relative_name}, line #{line_no}"
     meth.add_tokens [token, NEWLINE_TOKEN, indent]
     meth.add_tokens @token_stream
 
@@ -1200,7 +1250,7 @@ class RDoc::Parser::Ruby < RDoc::Parser
       when end_token then
         if end_token == TkRPAREN
           nest -= 1
-          break if @scanner.lex_state == EXPR_END and nest <= 0
+          break if nest <= 0
         else
           break unless @scanner.continue
         end
@@ -1344,7 +1394,7 @@ class RDoc::Parser::Ruby < RDoc::Parser
           non_comment_seen = true
         end
 
-        unget_tk tk # TODO peek instead of get then unget
+        unget_tk tk
         keep_comment = true
 
       when TkCLASS then
@@ -1388,6 +1438,9 @@ class RDoc::Parser::Ruby < RDoc::Parser
       when TkCASE, TkDO, TkIF, TkUNLESS, TkBEGIN then
         nest += 1
 
+      when TkSUPER then
+        current_method.calls_super = true if current_method
+
       when TkIDENTIFIER then
         if nest == 1 and current_method.nil? then
           case tk.name
@@ -1409,7 +1462,11 @@ class RDoc::Parser::Ruby < RDoc::Parser
               when /^# +:?attr(_reader|_writer|_accessor)?:/ then
                 parse_meta_attr container, single, tk, comment
               else
-                parse_meta_method container, single, tk, comment
+                method = parse_meta_method container, single, tk, comment
+                method.params = container.params if
+                  container.params
+                method.block_params = container.block_params if
+                  container.block_params
               end
             end
           end
@@ -1420,6 +1477,8 @@ class RDoc::Parser::Ruby < RDoc::Parser
           parse_require container, comment
         when "include" then
           parse_include container, comment
+        when "extend" then
+          parse_extend container, comment
         end
 
       when TkEND then
@@ -1446,6 +1505,8 @@ class RDoc::Parser::Ruby < RDoc::Parser
       unless keep_comment then
         comment = new_comment ''
         comment.force_encoding @encoding if @encoding
+        container.params = nil
+        container.block_params = nil
       end
 
       begin
@@ -1453,6 +1514,9 @@ class RDoc::Parser::Ruby < RDoc::Parser
         skip_tkspace false
       end while peek_tk == TkNL
     end
+
+    container.params = nil
+    container.block_params = nil
   end
 
   ##
@@ -1641,28 +1705,44 @@ class RDoc::Parser::Ruby < RDoc::Parser
   #
   #   class MyClass # :nodoc:
   #
-  # We return the directive name and any parameters as a two element array
+  # We return the directive name and any parameters as a two element array if
+  # the name is in +allowed+.  A directive can be found anywhere up to the end
+  # of the current line.
 
   def read_directive allowed
-    tk = get_tk
+    tokens = []
 
-    if TkCOMMENT === tk then
-      return unless tk.text =~ /\s*:?(\w+):\s*(.*)/
+    while tk = get_tk do
+      tokens << tk
+
+      case tk
+      when TkNL      then return
+      when TkCOMMENT then
+        return unless tk.text =~ /\s*:?([\w-]+):\s*(.*)/
 
-      directive = $1.downcase
+        directive = $1.downcase
 
-      return [directive, $2] if allowed.include? directive
-    else
-      unget_tk tk
+        return [directive, $2] if allowed.include? directive
+
+        return
+      end
+    end
+  ensure
+    unless tokens.length == 1 and TkCOMMENT === tokens.first then
+      tokens.reverse_each do |token|
+        unget_tk token
+      end
     end
   end
 
   ##
-  # Handles the directive for +context+ if the directive is listed in +allow+.
-  # This method is called for directives following a definition.
+  # Handles directives following the definition for +context+ (any
+  # RDoc::CodeObject) if the directives are +allowed+ at this point.
+  #
+  # See also RDoc::Markup::PreProcess#handle_directive
 
-  def read_documentation_modifiers context, allow
-    directive, value = read_directive allow
+  def read_documentation_modifiers context, allowed
+    directive, value = read_directive allowed
 
     return unless directive
 

data/lib/rdoc/parser/ruby_tools.rb

@@ -43,8 +43,7 @@ module RDoc::Parser::RubyTools
           tk = Token(TkSYMBOL).set_text(":" + tk1.text)
         end
 
-        # remove the identifier we just read (we're about to replace it with a
-        # symbol)
+        # remove the identifier we just read to replace it with a symbol
         @token_listeners.each do |obj|
           obj.pop_token
         end if @token_listeners
@@ -70,7 +69,13 @@ module RDoc::Parser::RubyTools
 
     loop do
       tk = get_tk
-      case tk when *tokens then unget_tk tk; break end
+
+      case tk
+      when *tokens then
+        unget_tk tk
+        break
+      end
+
       read << tk
     end
 

data/lib/rdoc/rd.rb

@@ -1,7 +1,11 @@
 ##
 # RDoc::RD implements the RD format from the rdtool gem.
 #
-# = LICENSE
+# To choose RD as your only default format see
+# RDoc::Options@Saved+Options for instructions on setting up a
+# <code>.doc_options</code> file to store your project default.
+#
+# == LICENSE
 #
 # The grammar that produces RDoc::RD::BlockParser and RDoc::RD::InlineParser
 # is included in RDoc under the Ruby License.
@@ -10,7 +14,7 @@
 # https://github.com/uwabami/rdtool/
 #
 # You can use, re-distribute or change these files under Ruby's License or GPL.
-# 
+#
 # 1. You may make and give away verbatim copies of the source form of the
 #    software without restriction, provided that you duplicate all of the
 #    original copyright notices and associated disclaimers.
@@ -53,9 +57,9 @@
 #    For the list of those files and their copying conditions, see the
 #    file LEGAL.
 #
-# 5. The scripts and library files supplied as input to or produced as 
+# 5. The scripts and library files supplied as input to or produced as
 #    output from the software do not automatically fall under the
-#    copyright of the software, but belong to whomever generated them, 
+#    copyright of the software, but belong to whomever generated them,
 #    and may be sold commercially, and may be aggregated with this
 #    software.
 #

data/lib/rdoc/rd/block_parser.rb

@@ -10,7 +10,7 @@ class RDoc::RD
 
 ##
 # RD format parser for headings, paragraphs, lists, verbatim sections that
-# exist as blocks.  
+# exist as blocks.
 
 class BlockParser < Racc::Parser
 

data/lib/rdoc/rd/block_parser.ry

@@ -632,7 +632,7 @@ class RDoc::RD
 
 ##
 # RD format parser for headings, paragraphs, lists, verbatim sections that
-# exist as blocks.  
+# exist as blocks.
 
 ---- footer
 end