Add missing documents

Rakefile

@@ -27,6 +27,14 @@ RDoc::Task.new do |doc|
   doc.rdoc_files = FileList.new %w[lib/**/*.rb *.rdoc doc/rdoc/markup_reference.rb] - PARSER_FILES
 end
 
+task "coverage" do
+  cov = []
+  e = IO.popen([FileUtils::RUBY, "-I./lib", "exe/rdoc", "-C"], &:read)
+  e.scan(/^ *# in file (?<loc>.*)\n *(?<code>.*)|^ *(?<code>.*\S) *# in file (?<loc>.*)/) do
+    puts "%s: %s\n" % $~.values_at(:loc, :code)
+  end
+end
+
 Rake::TestTask.new(:normal_test) do |t|
   t.verbose = true
   t.deps = :generate

lib/rdoc.rb

@@ -120,6 +120,17 @@ def self.load_yaml
     end
   end
 
+  ##
+  # Seaches and returns the directory for settings.
+  #
+  # 1. <tt>$HOME/.rdoc</tt> directory, if it exists.
+  # 2. The +rdoc+ directory under the path specified by the
+  #    +XDG_DATA_HOME+ environment variable, if it is set.
+  # 3. <tt>$HOME/.local/share/rdoc</tt> directory.
+  #
+  # Other than the home directory, the containing directory will be
+  # created automatically.
+
   def self.home
     rdoc_dir = begin
                 File.expand_path('~/.rdoc')
@@ -129,6 +140,7 @@ def self.home
     if File.directory?(rdoc_dir)
       rdoc_dir
     else
+      require 'fileutils'
       begin
         # XDG
         xdg_data_home = ENV["XDG_DATA_HOME"] || File.join(File.expand_path("~"), '.local', 'share')

lib/rdoc/cross_reference.rb

@@ -131,6 +131,9 @@ def initialize context
     @seen = {}
   end
 
+  ##
+  # Returns a method reference to +name+.
+
   def resolve_method name
     ref = nil
 

lib/rdoc/encoding.rb

@@ -86,17 +86,6 @@ def self.read_file filename, encoding, force_transcode = false
     nil
   end
 
-  def self.remove_frozen_string_literal string
-    string =~ /\A(?:#!.*\n)?(.*\n)/
-    first_line = $1
-
-    if first_line =~ /\A# +frozen[-_]string[-_]literal[=:].+$/i
-      string = string.sub first_line, ''
-    end
-
-    string
-  end
-
   ##
   # Detects the encoding of +string+ based on the magic comment
 

lib/rdoc/generator/pot.rb

@@ -81,6 +81,7 @@ def generate
     end
   end
 
+  # :nodoc:
   def class_dir
     nil
   end

lib/rdoc/markdown/literals.kpeg

@@ -6,7 +6,6 @@
 # :markup: markdown
 
 ##
-#--
 # This set of literals is for Ruby 1.9 regular expressions and gives full
 # unicode support.
 #
@@ -20,4 +19,3 @@ BOM               = "\uFEFF"
 Newline           = /\n|\r\n?|\p{Zl}|\p{Zp}/
 NonAlphanumeric   = /\p{^Word}/
 Spacechar         = /\t|\p{Zs}/
-

lib/rdoc/markup/attribute_manager.rb

@@ -138,6 +138,7 @@ def copy_string(start_pos, end_pos)
     res
   end
 
+  # :nodoc:
   def exclusive?(attr)
     (attr & @exclusive_bitmap) != 0
   end
@@ -155,6 +156,7 @@ def convert_attrs(str, attrs, exclusive = false)
     convert_attrs_word_pair_map(str, attrs, exclusive)
   end
 
+  # :nodoc:
   def convert_attrs_matching_word_pairs(str, attrs, exclusive)
     # first do matching ones
     tags = @matching_word_pairs.select { |start, bitmap|
@@ -179,6 +181,7 @@ def convert_attrs_matching_word_pairs(str, attrs, exclusive)
     str.delete!(NON_PRINTING_START + NON_PRINTING_END)
   end
 
+  # :nodoc:
   def convert_attrs_word_pair_map(str, attrs, exclusive)
     # then non-matching
     unless @word_pair_map.empty? then

lib/rdoc/markup/parser.rb

@@ -420,6 +420,8 @@ def peek_token
   # A simple wrapper of StringScanner that is aware of the current column and lineno
 
   class MyStringScanner
+    # :stopdoc:
+
     def initialize(input)
       @line = @column = 0
       @s = StringScanner.new input
@@ -456,6 +458,8 @@ def matched
     def [](i)
       @s[i]
     end
+
+    #:startdoc:
   end
 
   ##

lib/rdoc/markup/table.rb

@@ -3,12 +3,21 @@
 # A section of table
 
 class RDoc::Markup::Table
-  attr_accessor :header, :align, :body
+  # headers of each column
+  attr_accessor :header
 
+  # alignments of each column
+  attr_accessor :align
+
+  # body texts of each column
+  attr_accessor :body
+
+  # Creates new instance
   def initialize header, align, body
     @header, @align, @body = header, align, body
   end
 
+  # :stopdoc:
   def == other
     self.class == other.class and
       @header == other.header and
@@ -20,7 +29,7 @@ def accept visitor
     visitor.accept_table @header, @body, @align
   end
 
-  def pretty_print q # :nodoc:
+  def pretty_print q
     q.group 2, '[Table: ', ']' do
       q.group 2, '[Head: ', ']' do
         q.seplist @header.zip(@align) do |text, align|

lib/rdoc/markup/to_html.rb

@@ -61,6 +61,7 @@ def initialize options, markup = nil
   #
   # These methods are used by regexp handling markup added by RDoc::Markup#add_regexp_handling.
 
+  # :nodoc:
   URL_CHARACTERS_REGEXP_STR = /[A-Za-z0-9\-._~:\/\?#\[\]@!$&'\(\)*+,;%=]/.source
 
   ##

lib/rdoc/markup/to_html_crossref.rb

@@ -42,6 +42,7 @@ def initialize(options, from_path, context, markup = nil)
     @cross_reference = RDoc::CrossReference.new @context
   end
 
+  # :nodoc:
   def init_link_notation_regexp_handlings
     add_regexp_handling_RDOCLINK
 

lib/rdoc/markup/to_html_snippet.rb

@@ -66,6 +66,9 @@ def accept_heading heading
 
   alias accept_rule ignore
 
+  ##
+  # Adds +paragraph+ to the output
+
   def accept_paragraph paragraph
     para = @in_list_entry.last || "<p>"
 

lib/rdoc/parser/c.rb

@@ -1215,6 +1215,9 @@ def scan
     @top_level
   end
 
+  ##
+  # Creates a RDoc::Comment instance.
+
   def new_comment text = nil, location = nil, language = nil
     RDoc::Comment.new(text, location, language).tap do |comment|
       comment.format = @markup

lib/rdoc/parser/changelog.rb

@@ -216,12 +216,22 @@ def scan
     @top_level
   end
 
+  ##
+  # The extension for Git commit log
+
   module Git
+    ##
+    # Parses auxiliary info.  Currentry `base-url` to expand
+    # references is effective.
+
     def parse_info(info)
       /^\s*base-url\s*=\s*(.*\S)/ =~ info
       @base_url = $1
     end
 
+    ##
+    # Parses the entries in the Git commit logs
+
     def parse_entries
       entries = []
 
@@ -244,6 +254,11 @@ def parse_entries
       entries
     end
 
+    ##
+    # Returns a list of ChangeLog entries as
+    # RDoc::Parser::ChangeLog::Git::LogEntry list for the given
+    # +entries+.
+
     def create_entries entries
       # git log entries have no strictly itemized style like the old
       # style, just assume Markdown.

lib/rdoc/parser/ripper_state_lex.rb

@@ -1,7 +1,12 @@
 # frozen_string_literal: true
 require 'ripper'
 
+##
+# Wrapper for Ripper lex states
+
 class RDoc::Parser::RipperStateLex
+  # :stopdoc:
+
   # TODO: Remove this constants after Ruby 2.4 EOL
   RIPPER_HAS_LEX_STATE = Ripper::Filter.method_defined?(:state)
 
@@ -565,13 +570,17 @@ def get_squashed_tk
     tk
   end
 
+  # :startdoc:
+
+  # New lexer for +code+.
   def initialize(code)
     @buf = []
     @heredoc_queue = []
     @inner_lex = InnerStateLex.new(code)
     @tokens = @inner_lex.parse([])
   end
 
+  # Returns tokens parsed from +code+.
   def self.parse(code)
     lex = self.new(code)
     tokens = []
@@ -584,6 +593,7 @@ def self.parse(code)
     tokens
   end
 
+  # Returns +true+ if lex state will be +END+ after +token+.
   def self.end?(token)
     (token[:state] & EXPR_END)
   end

lib/rdoc/parser/ruby.rb

@@ -180,6 +180,9 @@ def initialize(top_level, file_name, content, options, stats)
     reset
   end
 
+  ##
+  # Return +true+ if +tk+ is a newline.
+
   def tk_nl?(tk)
     :on_nl == tk[:kind] or :on_ignored_nl == tk[:kind]
   end

lib/rdoc/store.rb

@@ -197,6 +197,9 @@ def add_file absolute_name, relative_name: absolute_name, parser: nil
     top_level
   end
 
+  ##
+  # Sets the parser of +absolute_name+, unless it from a source code file.
+
   def update_parser_of_file(absolute_name, parser)
     if top_level = @files_hash[absolute_name] then
       @text_files_hash[absolute_name] = top_level if top_level.text?

lib/rdoc/text.rb

@@ -10,6 +10,10 @@
 
 module RDoc::Text
 
+  ##
+  # The language for this text.  This affects stripping comments
+  # markers.
+
   attr_accessor :language
 
   ##

lib/rdoc/top_level.rb

@@ -52,6 +52,9 @@ def initialize absolute_name, relative_name = absolute_name
     @classes_or_modules = []
   end
 
+  ##
+  # Sets the parser for this toplevel context, also the store.
+
   def parser=(val)
     @parser = val
     @store.update_parser_of_file(absolute_name, val) if @store