rdoc 2.4.3 → 2.5

data/lib/rdoc/ruby_token.rb

@@ -0,0 +1,416 @@
+#--
+#   irb/ruby-token.rb - ruby tokens 
+#   	$Release Version: 0.9.5$
+#   	$Revision: 11708 $
+#   	$Date: 2007-02-12 15:01:19 -0800 (Mon, 12 Feb 2007) $
+#   	by Keiju ISHITSUKA(keiju@ruby-lang.org)
+#++
+# Definitions of all tokens involved in the lexical analysis.
+#
+# This class is not documented because it is so deep in the internals.
+
+module RDoc::RubyToken
+  # :stopdoc:
+
+  EXPR_BEG = :EXPR_BEG
+  EXPR_MID = :EXPR_MID
+  EXPR_END = :EXPR_END
+  EXPR_ARG = :EXPR_ARG
+  EXPR_FNAME = :EXPR_FNAME
+  EXPR_DOT = :EXPR_DOT
+  EXPR_CLASS = :EXPR_CLASS
+
+  # for ruby 1.4X
+  if !defined?(Symbol)
+    Symbol = Integer
+  end
+
+  def set_token_position(line, char)
+    @prev_line_no = line
+    @prev_char_no = char
+  end
+
+  class Token
+    def initialize(seek, line_no, char_no, text = nil)
+      @seek = seek
+      @line_no = line_no
+      @char_no = char_no
+      @text = text
+    end
+
+    attr :seek
+    attr :line_no
+    attr :char_no
+
+    attr_accessor :text
+
+    def ==(other)
+      self.class == other.class and
+      other.line_no == @line_no and
+      other.char_no == @char_no and
+      other.text == @text
+    end
+
+    ##
+    # Because we're used in contexts that expect to return a token, we set the
+    # text string and then return ourselves
+
+    def set_text(text)
+      @text = text
+      self
+    end
+
+  end
+
+  class TkNode < Token
+    def initialize(seek, line_no, char_no, node = nil)
+      super seek, line_no, char_no
+      @node = node
+    end
+
+    attr :node
+
+    def ==(other)
+      self.class == other.class and
+      other.line_no == @line_no and
+      other.char_no == @char_no and
+      other.node == @node
+    end
+
+    def set_text text
+      @node = text
+      self
+    end
+
+    alias text node
+  end
+
+  class TkId < Token
+    def initialize(seek, line_no, char_no, name)
+      super(seek, line_no, char_no)
+      @name = name
+    end
+    attr :name
+
+    def ==(other)
+      self.class == other.class and
+      other.line_no == @line_no and
+      other.char_no == @char_no and
+      other.name == @name
+    end
+
+    def set_text text
+      @name = text
+      self
+    end
+
+    alias text name
+  end
+
+  class TkKW < TkId
+  end
+
+  class TkVal < Token
+    def initialize(seek, line_no, char_no, value = nil)
+      super(seek, line_no, char_no)
+      @value = value
+    end
+    attr_accessor :value
+
+    def ==(other)
+      self.class == other.class and
+      other.line_no == @line_no and
+      other.char_no == @char_no and
+      other.value == @value
+    end
+
+    def set_text text
+      @value = text
+      self
+    end
+
+    alias text value
+  end
+
+  class TkOp < Token
+    def initialize(seek, line_no, char_no, name = nil)
+      super seek, line_no, char_no
+      @name = name
+    end
+
+    attr_accessor :name
+
+    def ==(other)
+      self.class == other.class and
+      other.line_no == @line_no and
+      other.char_no == @char_no and
+      other.name == @name
+    end
+
+    def set_text text
+      @name = text
+      self
+    end
+
+    alias text name
+  end
+
+  class TkOPASGN < TkOp
+    def initialize(seek, line_no, char_no, op)
+      super(seek, line_no, char_no)
+      op = TkReading2Token[op][0] unless op.kind_of?(Symbol)
+      @op = op
+      @text = nil
+    end
+
+    attr :op
+
+    def ==(other)
+      self.class == other.class and
+      other.line_no == @line_no and
+      other.char_no == @char_no and
+      other.op == @op
+    end
+
+    def text
+      @text ||= "#{TkToken2Reading[op]}="
+    end
+  end
+
+  class TkUnknownChar < Token
+    def initialize(seek, line_no, char_no, id)
+      super(seek, line_no, char_no)
+      @name = name
+    end
+    attr :name
+
+    def ==(other)
+      self.class == other.class and
+      other.line_no == @line_no and
+      other.char_no == @char_no and
+      other.name == @name
+    end
+
+    def set_text text
+      @name = text
+      self
+    end
+
+    alias text name
+  end
+
+  class TkError < Token
+  end
+
+  def Token(token, value = nil)
+    value ||= TkToken2Reading[token]
+
+    case token
+    when String
+      if (tk = TkReading2Token[token]).nil?
+        IRB.fail TkReading2TokenNoKey, token
+      end
+
+      tk = Token(tk[0], value) 
+
+      if tk.kind_of?(TkOp) then
+        tk.name = token
+      end
+    when Symbol
+      if (tk = TkSymbol2Token[token]).nil?
+        IRB.fail TkSymbol2TokenNoKey, token
+      end
+
+      tk = Token(tk[0], value) 
+    else 
+      if token.instance_method(:initialize).arity == 3 then
+        tk = token.new(@prev_seek, @prev_line_no, @prev_char_no)
+        tk.set_text value
+      else
+        tk = token.new(@prev_seek, @prev_line_no, @prev_char_no, value)
+      end
+    end
+
+    tk
+  end
+
+  TokenDefinitions = [
+    [:TkCLASS,      TkKW,  "class",  EXPR_CLASS],
+    [:TkMODULE,     TkKW,  "module", EXPR_BEG],
+    [:TkDEF,        TkKW,  "def",    EXPR_FNAME],
+    [:TkUNDEF,      TkKW,  "undef",  EXPR_FNAME],
+    [:TkBEGIN,      TkKW,  "begin",  EXPR_BEG],
+    [:TkRESCUE,     TkKW,  "rescue", EXPR_MID],
+    [:TkENSURE,     TkKW,  "ensure", EXPR_BEG],
+    [:TkEND,        TkKW,  "end",    EXPR_END],
+    [:TkIF,         TkKW,  "if",     EXPR_BEG, :TkIF_MOD],
+    [:TkUNLESS,     TkKW,  "unless", EXPR_BEG, :TkUNLESS_MOD],
+    [:TkTHEN,       TkKW,  "then",   EXPR_BEG],
+    [:TkELSIF,      TkKW,  "elsif",  EXPR_BEG],
+    [:TkELSE,       TkKW,  "else",   EXPR_BEG],
+    [:TkCASE,       TkKW,  "case",   EXPR_BEG],
+    [:TkWHEN,       TkKW,  "when",   EXPR_BEG],
+    [:TkWHILE,      TkKW,  "while",  EXPR_BEG, :TkWHILE_MOD],
+    [:TkUNTIL,      TkKW,  "until",  EXPR_BEG, :TkUNTIL_MOD],
+    [:TkFOR,        TkKW,  "for",    EXPR_BEG],
+    [:TkBREAK,      TkKW,  "break",  EXPR_END],
+    [:TkNEXT,       TkKW,  "next",   EXPR_END],
+    [:TkREDO,       TkKW,  "redo",   EXPR_END],
+    [:TkRETRY,      TkKW,  "retry",  EXPR_END],
+    [:TkIN,         TkKW,  "in",     EXPR_BEG],
+    [:TkDO,         TkKW,  "do",     EXPR_BEG],
+    [:TkRETURN,     TkKW,  "return", EXPR_MID],
+    [:TkYIELD,      TkKW,  "yield",  EXPR_END],
+    [:TkSUPER,      TkKW,  "super",  EXPR_END],
+    [:TkSELF,       TkKW,  "self",   EXPR_END],
+    [:TkNIL,        TkKW,  "nil",    EXPR_END],
+    [:TkTRUE,       TkKW,  "true",   EXPR_END],
+    [:TkFALSE,      TkKW,  "false",  EXPR_END],
+    [:TkAND,        TkKW,  "and",    EXPR_BEG],
+    [:TkOR,         TkKW,  "or",     EXPR_BEG],
+    [:TkNOT,        TkKW,  "not",    EXPR_BEG],
+    [:TkIF_MOD,     TkKW],
+    [:TkUNLESS_MOD, TkKW],
+    [:TkWHILE_MOD,  TkKW],
+    [:TkUNTIL_MOD,  TkKW],
+    [:TkALIAS,      TkKW,  "alias",    EXPR_FNAME],
+    [:TkDEFINED,    TkKW,  "defined?", EXPR_END],
+    [:TklBEGIN,     TkKW,  "BEGIN",    EXPR_END],
+    [:TklEND,       TkKW,  "END",      EXPR_END],
+    [:Tk__LINE__,   TkKW,  "__LINE__", EXPR_END],
+    [:Tk__FILE__,   TkKW,  "__FILE__", EXPR_END],
+
+    [:TkIDENTIFIER, TkId],
+    [:TkFID,        TkId],
+    [:TkGVAR,       TkId],
+    [:TkCVAR,       TkId],
+    [:TkIVAR,       TkId],
+    [:TkCONSTANT,   TkId],
+
+    [:TkINTEGER,    TkVal],
+    [:TkFLOAT,      TkVal],
+    [:TkSTRING,     TkVal],
+    [:TkXSTRING,    TkVal],
+    [:TkREGEXP,     TkVal],
+    [:TkSYMBOL,     TkVal],
+
+    [:TkDSTRING,    TkNode],
+    [:TkDXSTRING,   TkNode],
+    [:TkDREGEXP,    TkNode],
+    [:TkNTH_REF,    TkNode],
+    [:TkBACK_REF,   TkNode],
+
+    [:TkUPLUS,      TkOp,   "+@"],
+    [:TkUMINUS,     TkOp,   "-@"],
+    [:TkPOW,        TkOp,   "**"],
+    [:TkCMP,        TkOp,   "<=>"],
+    [:TkEQ,         TkOp,   "=="],
+    [:TkEQQ,        TkOp,   "==="],
+    [:TkNEQ,        TkOp,   "!="],
+    [:TkGEQ,        TkOp,   ">="],
+    [:TkLEQ,        TkOp,   "<="],
+    [:TkANDOP,      TkOp,   "&&"],
+    [:TkOROP,       TkOp,   "||"],
+    [:TkMATCH,      TkOp,   "=~"],
+    [:TkNMATCH,     TkOp,   "!~"],
+    [:TkDOT2,       TkOp,   ".."],
+    [:TkDOT3,       TkOp,   "..."],
+    [:TkAREF,       TkOp,   "[]"],
+    [:TkASET,       TkOp,   "[]="],
+    [:TkLSHFT,      TkOp,   "<<"],
+    [:TkRSHFT,      TkOp,   ">>"],
+    [:TkCOLON2,     TkOp,   '::'],
+    [:TkCOLON3,     TkOp,   '::'],
+    #[:OPASGN,       TkOp],               # +=, -=  etc. #
+    [:TkASSOC,      TkOp,   "=>"],
+    [:TkQUESTION,   TkOp,   "?"], #?
+    [:TkCOLON,      TkOp,   ":"],        #:
+
+    [:TkfLPAREN,    Token,  "("], # func( #
+    [:TkfLBRACK,    Token,  "["], # func[ #
+    [:TkfLBRACE,    Token,  "{"], # func{ #
+    [:TkSTAR,       Token,  "*"], # *arg
+    [:TkAMPER,      Token,  "&"], # &arg #
+    [:TkSYMBEG,     Token,  ":"], # :SYMBOL
+
+    [:TkGT,         TkOp,   ">"],
+    [:TkLT,         TkOp,   "<"],
+    [:TkPLUS,       TkOp,   "+"],
+    [:TkMINUS,      TkOp,   "-"],
+    [:TkMULT,       TkOp,   "*"],
+    [:TkDIV,        TkOp,   "/"],
+    [:TkMOD,        TkOp,   "%"],
+    [:TkBITOR,      TkOp,   "|"],
+    [:TkBITXOR,     TkOp,   "^"],
+    [:TkBITAND,     TkOp,   "&"],
+    [:TkBITNOT,     TkOp,   "~"],
+    [:TkNOTOP,      TkOp,   "!"],
+
+    [:TkBACKQUOTE,  TkOp,   "`"],
+
+    [:TkASSIGN,     Token,  "="],
+    [:TkDOT,        Token,  "."],
+    [:TkLPAREN,     Token,  "("],  #(exp)
+    [:TkLBRACK,     Token,  "["],  #[arry]
+    [:TkLBRACE,     Token,  "{"],  #{hash}
+    [:TkRPAREN,     Token,  ")"],
+    [:TkRBRACK,     Token,  "]"],
+    [:TkRBRACE,     Token,  "}"],
+    [:TkCOMMA,      Token,  ","],
+    [:TkSEMICOLON,  Token,  ";"],
+
+    [:TkCOMMENT,    TkVal],
+    [:TkRD_COMMENT],
+    [:TkSPACE,      Token,  " "],
+    [:TkNL,         Token,  "\n"],
+    [:TkEND_OF_SCRIPT],
+
+    [:TkBACKSLASH,  TkUnknownChar,  "\\"],
+    [:TkAT,         TkUnknownChar,  "@"],
+    [:TkDOLLAR,     TkUnknownChar,  "$"],
+  ]
+
+  # {reading => token_class}
+  # {reading => [token_class, *opt]}
+  TkReading2Token = {}
+  TkToken2Reading = {}
+  TkSymbol2Token = {}
+
+  def self.def_token(token_n, super_token = Token, reading = nil, *opts)
+    token_n = token_n.id2name if token_n.kind_of?(Symbol)
+    if const_defined?(token_n)
+      IRB.fail AlreadyDefinedToken, token_n
+    end
+    token_c = eval("class #{token_n} < #{super_token}; end; #{token_n}")
+
+    if reading
+      TkToken2Reading[token_c] = reading
+
+      return if TkReading2Token[reading]
+
+      if opts.empty?
+        TkReading2Token[reading] = [token_c]
+      else
+        TkReading2Token[reading] = [token_c].concat(opts)
+      end
+    end
+    TkSymbol2Token[token_n.intern] = token_c
+  end
+
+  for defs in TokenDefinitions
+    def_token(*defs)
+  end
+
+  NEWLINE_TOKEN = TkNL.new nil, 0, 0, "\n"
+
+  class TkSYMBOL
+
+    def to_sym
+      @sym ||= text[1..-1].intern
+    end
+
+  end
+
+  # :startdoc:
+end
+

data/lib/rdoc/single_class.rb

@@ -4,5 +4,10 @@ require 'rdoc/class_module'
 # A singleton class
 
 class RDoc::SingleClass < RDoc::ClassModule
+
+  def ancestors
+    includes + [superclass]
+  end
+
 end
 

data/lib/rdoc/stats.rb

@@ -1,113 +1,177 @@
 require 'rdoc'
-require 'thread'
 
 ##
-# Simple stats collector
+# RDoc stats collector
 
 class RDoc::Stats
 
-  attr_reader :num_classes
+  attr_reader :nodoc_constants
+  attr_reader :nodoc_methods
+
+  attr_reader :num_constants
   attr_reader :num_files
   attr_reader :num_methods
-  attr_reader :num_modules
+
   attr_reader :total_files
 
   def initialize(total_files, verbosity = 1)
-    @lock = Mutex.new
-    
-    @num_classes = 0
-    @num_files   = 0
-    @num_methods = 0
-    @num_modules = 0
+    @nodoc_constants = 0
+    @nodoc_methods   = 0
+
+    @num_constants = 0
+    @num_files     = 0
+    @num_methods   = 0
+
     @total_files = total_files
 
     @start = Time.now
 
     @display = case verbosity
-               when 0 then Quiet.new
-               when 1 then Normal.new(total_files)
-               else        Verbose.new
+               when 0 then Quiet.new   total_files
+               when 1 then Normal.new  total_files
+               else        Verbose.new total_files
                end
   end
-  
-  def begin_adding(number_of_workers)
-    @display.begin_adding(number_of_workers)
+
+  def begin_adding
+    @display.begin_adding
   end
 
   def add_alias(as)
-    @lock.synchronize do
-      @display.print_alias as
-      @num_methods += 1
-    end
+    @display.print_alias as
+    @num_methods += 1
+    @nodoc_methods += 1 if as.document_self and as.comment.empty?
   end
 
   def add_class(klass)
-    @lock.synchronize do
-      @display.print_class klass
-      @num_classes += 1
-    end
+    @display.print_class klass
+  end
+
+  def add_constant(constant)
+    @display.print_constant constant
+    @num_constants += 1
+    @nodoc_constants += 1 if constant.document_self and constant.comment.empty?
   end
 
   def add_file(file)
-    @lock.synchronize do
-      @display.print_file @num_files, file
-      @num_files += 1
-    end
+    @display.print_file @num_files, file
+    @num_files += 1
   end
 
   def add_method(method)
-    @lock.synchronize do
-      @display.print_method method
-      @num_methods += 1
-    end
+    @display.print_method method
+    @num_methods += 1
+    @nodoc_methods += 1 if method.document_self and method.comment.empty?
   end
 
   def add_module(mod)
-    @lock.synchronize do
-      @display.print_module mod
-      @num_modules += 1
-    end
+    @display.print_module mod
   end
-  
+
   def done_adding
-    @lock.synchronize do
-      @display.done_adding
-    end
+    @display.done_adding
   end
 
   def print
-    puts "Files:   #@num_files"
-    puts "Classes: #@num_classes"
-    puts "Modules: #@num_modules"
-    puts "Methods: #@num_methods"
-    puts "Elapsed: " + sprintf("%0.1fs", Time.now - @start)
+    classes = RDoc::TopLevel.classes
+    num_classes   = classes.length
+    nodoc_classes = classes.select do |klass|
+      klass.document_self and klass.comment.empty?
+    end.length
+
+    modules = RDoc::TopLevel.modules
+    num_modules = modules.length
+    nodoc_modules = modules.select do |mod|
+      mod.document_self and mod.comment.empty?
+    end.length
+
+    items = num_classes + @num_constants + num_modules + @num_methods
+    doc_items = items -
+      nodoc_classes - @nodoc_constants - nodoc_modules - @nodoc_methods
+
+    percent_doc = doc_items.to_f / items * 100
+
+    puts "Files:     %5d" % @num_files
+    puts "Classes:   %5d (%5d undocumented)" % [num_classes, nodoc_classes]
+    puts "Constants: %5d (%5d undocumented)" %
+      [@num_constants, @nodoc_constants]
+    puts "Modules:   %5d (%5d undocumented)" % [num_modules, nodoc_modules]
+    puts "Methods:   %5d (%5d undocumented)" % [@num_methods, @nodoc_methods]
+    puts "%6.2f%% documented" % percent_doc
+    puts
+    puts "Elapsed: %0.1fs" % (Time.now - @start)
   end
 
+  ##
+  # Stats printer that prints nothing
+
   class Quiet
+
+    def initialize total_files
+      @total_files = total_files
+    end
+
+    ##
+    # Prints a message at the beginning of parsing
+
     def begin_adding(*) end
+
+    ##
+    # Prints when an alias is added
+
     def print_alias(*) end
+
+    ##
+    # Prints when a class is added
+
     def print_class(*) end
+
+    ##
+    # Prints when a constant is added
+
+    def print_constant(*) end
+
+    ##
+    # Prints when a file is added
+
     def print_file(*) end
+
+    ##
+    # Prints when a method is added
+
     def print_method(*) end
+
+    ##
+    # Prints when a module is added
+
     def print_module(*) end
+
+    ##
+    # Prints when RDoc is done
+
     def done_adding(*) end
+
   end
-  
-  class Normal
-    def initialize(total_files)
-      @total_files = total_files
-    end
-    
-    def begin_adding(number_of_workers)
-      puts "Parsing sources with #{number_of_workers} thread(s)..."
+
+  ##
+  # Stats printer that prints just the files being documented with a progress
+  # bar
+
+  class Normal < Quiet
+
+    def begin_adding # :nodoc:
+      puts "Parsing sources..."
     end
-    
+
+    ##
+    # Prints a file with a progress bar
+
     def print_file(files_so_far, filename)
       progress_bar = sprintf("%3d%% [%2d/%2d]  ",
                              100 * (files_so_far + 1) / @total_files,
                              files_so_far + 1,
                              @total_files)
-      
+
       if $stdout.tty?
         # Print a progress bar, but make sure it fits on a single line. Filename
         # will be truncated if necessary.
@@ -118,59 +182,64 @@ class RDoc::Stats
           filename = filename[(filename.size - max_filename_size) .. -1]
           filename[0..2] = "..."
         end
-        
+
         # Pad the line with whitespaces so that leftover output from the
         # previous line doesn't show up.
         line = "#{progress_bar}#{filename}"
         padding = terminal_width - line.size
-        if padding > 0
-          line << (" " * padding)
-        end
-        
+        line << (" " * padding) if padding > 0
+
         $stdout.print("#{line}\r")
         $stdout.flush
       else
         puts "#{progress_bar} #{filename}"
       end
     end
-    
-    def done_adding
-      puts "\n"
+
+    def done_adding # :nodoc:
+      puts
     end
 
-    def print_alias(*) end
-    def print_class(*) end
-    def print_method(*) end
-    def print_module(*) end
   end
 
-  class Verbose
-    def begin_adding(number_of_workers)
-      puts "Parsing sources with #{number_of_workers} thread(s)..."
+  ##
+  # Stats printer that prints everything documented, including the documented
+  # status
+
+  class Verbose < Normal
+
+    ##
+    # Returns a marker for RDoc::CodeObject +co+ being undocumented
+
+    def nodoc co
+      " (undocumented)" unless co.documented?
     end
-    
-    def print_alias(as)
-      puts "\t\talias #{as.new_name} #{as.old_name}"
+
+    def print_alias as # :nodoc:
+      puts "\t\talias #{as.new_name} #{as.old_name}#{nodoc as}"
     end
 
-    def print_class(klass)
-      puts "\tclass #{klass.full_name}"
+    def print_class(klass) # :nodoc:
+      puts "\tclass #{klass.full_name}#{nodoc klass}"
     end
 
-    def print_file(files_so_far, file)
-      puts file
+    def print_constant(constant) # :nodoc:
+      puts "\t\t#{constant.name}#{nodoc constant}"
     end
 
-    def print_method(method)
-      puts "\t\t#{method.singleton ? '::' : '#'}#{method.name}"
+    def print_file(files_so_far, file) # :nodoc:
+      super
+      puts
     end
 
-    def print_module(mod)
-      puts "\tmodule #{mod.full_name}"
+    def print_method(method) # :nodoc:
+      puts "\t\t#{method.singleton ? '::' : '#'}#{method.name}#{nodoc method}"
     end
-    
-    def done_adding
+
+    def print_module(mod) # :nodoc:
+      puts "\tmodule #{mod.full_name}#{nodoc mod}"
     end
+
   end
 
 end