[ruby/rdoc] [DOC] Add missing documents

https://github.com/ruby/rdoc/commit/e4c90340d0

12 files changed, 63 insertions, 2 deletions

diff --git a/lib/rdoc.rb b/lib/rdoc.rb
index 7bf2635c16..cf52ce8792 100644
--- a/lib/rdoc.rb
+++ b/lib/rdoc.rb
@@ -120,6 +120,17 @@ module RDoc
     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')
diff --git a/lib/rdoc/cross_reference.rb b/lib/rdoc/cross_reference.rb
index f3b703a559..4e011219e8 100644
--- a/lib/rdoc/cross_reference.rb
+++ b/lib/rdoc/cross_reference.rb
@@ -131,6 +131,9 @@ class RDoc::CrossReference
     @seen = {}
   end
 
+  ##
+  # Returns a method reference to +name+.
+
   def resolve_method name
     ref = nil
 
diff --git a/lib/rdoc/markdown/literals.rb b/lib/rdoc/markdown/literals.rb
index 37659b7ae0..c5c15d3100 100644
--- a/lib/rdoc/markdown/literals.rb
+++ b/lib/rdoc/markdown/literals.rb
@@ -3,7 +3,6 @@
 # :markup: markdown
 
 ##
-#--
 # This set of literals is for Ruby 1.9 regular expressions and gives full
 # unicode support.
 #
diff --git a/lib/rdoc/markup/table.rb b/lib/rdoc/markup/table.rb
index 7bcb10aff3..9ab1dc8ec9 100644
--- a/lib/rdoc/markup/table.rb
+++ b/lib/rdoc/markup/table.rb
@@ -3,8 +3,16 @@
 # 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
diff --git a/lib/rdoc/markup/to_html_snippet.rb b/lib/rdoc/markup/to_html_snippet.rb
index 8219f0b169..f471395a3a 100644
--- a/lib/rdoc/markup/to_html_snippet.rb
+++ b/lib/rdoc/markup/to_html_snippet.rb
@@ -66,6 +66,9 @@ class RDoc::Markup::ToHtmlSnippet < RDoc::Markup::ToHtml
 
   alias accept_rule ignore
 
+  ##
+  # Adds +paragraph+ to the output
+
   def accept_paragraph paragraph
     para = @in_list_entry.last || "<p>"
 
diff --git a/lib/rdoc/parser/c.rb b/lib/rdoc/parser/c.rb
index 5555818e9e..d668507dc2 100644
--- a/lib/rdoc/parser/c.rb
+++ b/lib/rdoc/parser/c.rb
@@ -1215,6 +1215,9 @@ class RDoc::Parser::C < RDoc::Parser
     @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
diff --git a/lib/rdoc/parser/changelog.rb b/lib/rdoc/parser/changelog.rb
index 2a685d1d79..a046241870 100644
--- a/lib/rdoc/parser/changelog.rb
+++ b/lib/rdoc/parser/changelog.rb
@@ -216,12 +216,22 @@ class RDoc::Parser::ChangeLog < RDoc::Parser
     @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 @@ class RDoc::Parser::ChangeLog < RDoc::Parser
       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.
diff --git a/lib/rdoc/parser/ripper_state_lex.rb b/lib/rdoc/parser/ripper_state_lex.rb
index 27d7373270..ff7c41829f 100644
--- a/lib/rdoc/parser/ripper_state_lex.rb
+++ b/lib/rdoc/parser/ripper_state_lex.rb
@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 require 'ripper'
 
+##
+# Wrapper for Ripper lex states
+
 class RDoc::Parser::RipperStateLex
   # TODO: Remove this constants after Ruby 2.4 EOL
   RIPPER_HAS_LEX_STATE = Ripper::Filter.method_defined?(:state)
@@ -565,6 +568,7 @@ class RDoc::Parser::RipperStateLex
     tk
   end
 
+  # New lexer for +code+.
   def initialize(code)
     @buf = []
     @heredoc_queue = []
@@ -572,6 +576,7 @@ class RDoc::Parser::RipperStateLex
     @tokens = @inner_lex.parse([])
   end
 
+  # Returns tokens parsed from +code+.
   def self.parse(code)
     lex = self.new(code)
     tokens = []
@@ -584,6 +589,7 @@ class RDoc::Parser::RipperStateLex
     tokens
   end
 
+  # Returns +true+ if lex state will be +END+ after +token+.
   def self.end?(token)
     (token[:state] & EXPR_END)
   end
diff --git a/lib/rdoc/parser/ruby.rb b/lib/rdoc/parser/ruby.rb
index 2c8a19f608..39c3bae4c4 100644
--- a/lib/rdoc/parser/ruby.rb
+++ b/lib/rdoc/parser/ruby.rb
@@ -180,6 +180,9 @@ class RDoc::Parser::Ruby < RDoc::Parser
     reset
   end
 
+  ##
+  # Return +true+ if +tk+ is a newline.
+
   def tk_nl?(tk)
     :on_nl == tk[:kind] or :on_ignored_nl == tk[:kind]
   end
diff --git a/lib/rdoc/store.rb b/lib/rdoc/store.rb
index 9fc540d317..fe749edc1c 100644
--- a/lib/rdoc/store.rb
+++ b/lib/rdoc/store.rb
@@ -197,6 +197,9 @@ class RDoc::Store
     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?
diff --git a/lib/rdoc/text.rb b/lib/rdoc/text.rb
index 7c97c61ffd..9804f81abe 100644
--- a/lib/rdoc/text.rb
+++ b/lib/rdoc/text.rb
@@ -10,6 +10,10 @@ require 'strscan'
 
 module RDoc::Text
 
+  ##
+  # The language for this text.  This affects stripping comments
+  # markers.
+
   attr_accessor :language
 
   ##
diff --git a/lib/rdoc/top_level.rb b/lib/rdoc/top_level.rb
index e6caa34ee3..3864f66431 100644
--- a/lib/rdoc/top_level.rb
+++ b/lib/rdoc/top_level.rb
@@ -52,6 +52,9 @@ class RDoc::TopLevel < RDoc::Context
     @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