[PATCH 5/4] nodoc some internals

[Eric Wong <e@80x24.org>]

We don't want to advertise an API we'd have to support
long-term
---
 lib/olddoc.rb           |  4 ++--
 lib/olddoc/gemspec.rb   |  2 +-
 lib/olddoc/history.rb   |  2 +-
 lib/olddoc/merge.rb     |  2 +-
 lib/olddoc/news_atom.rb |  2 +-
 lib/olddoc/news_rdoc.rb |  2 +-
 lib/olddoc/prepare.rb   |  2 +-
 lib/olddoc/readme.rb    |  2 +-
 lib/oldweb.rb           | 52 +++++++++++++++++++++++++++----------------------
 lib/rdoc/discover.rb    |  2 ++
 10 files changed, 40 insertions(+), 32 deletions(-)

diff --git a/lib/olddoc.rb b/lib/olddoc.rb
index 1621f85..d9bc384 100644
--- a/lib/olddoc.rb
+++ b/lib/olddoc.rb
@@ -1,7 +1,7 @@
 # Copyright (C) 2015-2016 all contributors <olddoc-public@80x24.org>
 # License: GPL-3.0+ <https://www.gnu.org/licenses/gpl-3.0.txt>
-module Olddoc
-  VERSION = '1.1.2'
+module Olddoc # :nodoc:
+  VERSION = '1.1.2' # :nodoc:
 
   autoload :Gemspec, 'olddoc/gemspec'
   autoload :History, 'olddoc/history'
diff --git a/lib/olddoc/gemspec.rb b/lib/olddoc/gemspec.rb
index f5f008d..f9f6417 100644
--- a/lib/olddoc/gemspec.rb
+++ b/lib/olddoc/gemspec.rb
@@ -1,7 +1,7 @@
 # Copyright (C) 2015-2016 all contributors <olddoc-public@80x24.org>
 # License: GPL-3.0+ <https://www.gnu.org/licenses/gpl-3.0.txt>
 # helper methods for gemspecs
-module Olddoc::Gemspec
+module Olddoc::Gemspec # :nodoc:
   include Olddoc::Readme
 
   def extra_rdoc_files(manifest)
diff --git a/lib/olddoc/history.rb b/lib/olddoc/history.rb
index 595994d..dcdf0fe 100644
--- a/lib/olddoc/history.rb
+++ b/lib/olddoc/history.rb
@@ -2,7 +2,7 @@
 # License: GPL-3.0+ <https://www.gnu.org/licenses/gpl-3.0.txt>
 require 'uri'
 
-module Olddoc::History
+module Olddoc::History # :nodoc:
   def initialize_history
     @tags = @old_summaries = nil
   end
diff --git a/lib/olddoc/merge.rb b/lib/olddoc/merge.rb
index b5dae65..de5e2ae 100644
--- a/lib/olddoc/merge.rb
+++ b/lib/olddoc/merge.rb
@@ -1,7 +1,7 @@
 # Copyright (C) 2015-2016 all contributors <olddoc-public@80x24.org>
 # License: GPL-3.0+ <https://www.gnu.org/licenses/gpl-3.0.txt>
 
-class Olddoc::Merge
+class Olddoc::Merge # :nodoc:
   def initialize(opts)
     @merge_html = opts["merge_html"] || {}
   end
diff --git a/lib/olddoc/news_atom.rb b/lib/olddoc/news_atom.rb
index a093e64..a9e8002 100644
--- a/lib/olddoc/news_atom.rb
+++ b/lib/olddoc/news_atom.rb
@@ -2,7 +2,7 @@
 # License: GPL-3.0+ <https://www.gnu.org/licenses/gpl-3.0.txt>
 require 'builder'
 
-module Olddoc::NewsAtom
+module Olddoc::NewsAtom # :nodoc:
   include Olddoc::History
   include Olddoc::Readme
 
diff --git a/lib/olddoc/news_rdoc.rb b/lib/olddoc/news_rdoc.rb
index e8c6a34..2427591 100644
--- a/lib/olddoc/news_rdoc.rb
+++ b/lib/olddoc/news_rdoc.rb
@@ -4,7 +4,7 @@
 #
 require 'tempfile'
 
-module Olddoc::NewsRdoc
+module Olddoc::NewsRdoc # :nodoc:
   include Olddoc::History
 
   def puts_tag(fp, tag)
diff --git a/lib/olddoc/prepare.rb b/lib/olddoc/prepare.rb
index f42bd04..f902fff 100644
--- a/lib/olddoc/prepare.rb
+++ b/lib/olddoc/prepare.rb
@@ -2,7 +2,7 @@
 # License: GPL-3.0+ <https://www.gnu.org/licenses/gpl-3.0.txt>
 
 require 'uri'
-class Olddoc::Prepare
+class Olddoc::Prepare # :nodoc:
   include Olddoc::NewsRdoc
   include Olddoc::NewsAtom
   include Olddoc::Readme
diff --git a/lib/olddoc/readme.rb b/lib/olddoc/readme.rb
index 423d18b..0b3ee97 100644
--- a/lib/olddoc/readme.rb
+++ b/lib/olddoc/readme.rb
@@ -2,7 +2,7 @@
 # License: GPL-3.0+ <https://www.gnu.org/licenses/gpl-3.0.txt>
 
 # helpers for parsing the top-level README file
-module Olddoc::Readme
+module Olddoc::Readme # :nodoc:
 
   def readme_path
     'README'
diff --git a/lib/oldweb.rb b/lib/oldweb.rb
index af62050..a5da1cc 100644
--- a/lib/oldweb.rb
+++ b/lib/oldweb.rb
@@ -8,11 +8,15 @@ require 'yaml'
 require 'cgi'
 require 'uri'
 
+# oldweb is an \RDoc template and not intended as a programming API.
+# You may specify it as an \RDoc formatter:
+#
+#   rdoc -f oldweb ...
 class Oldweb
-  RDoc::RDoc.add_generator(self)
-  include ERB::Util
-  attr_reader :class_dir
-  attr_reader :file_dir
+  RDoc::RDoc.add_generator(self) # :nodoc:
+  include ERB::Util # :nodoc:
+  attr_reader :class_dir # :nodoc:
+  attr_reader :file_dir # :nodoc:
 
   # description of the generator
   DESCRIPTION = 'minimal HTML generator'
@@ -20,7 +24,7 @@ class Oldweb
   # version of this generator
   VERSION = '1'
 
-  def initialize(store, options)
+  def initialize(store, options) # :nodoc:
     # just because we're capable of generating UTF-8 to get human names
     # right does not mean we should overuse it for quotation marks and such,
     # our clients may not have the necessary fonts.
@@ -76,7 +80,7 @@ class Oldweb
     end
   end
 
-  def generate
+  def generate # :nodoc:
     setup
     generate_class_files
     generate_file_files
@@ -90,13 +94,13 @@ class Oldweb
     end if src
   end
 
-  def rel_path(out_file)
+  def rel_path(out_file) # :nodoc:
     rel_prefix = @outputdir.relative_path_from(out_file.dirname)
     rel_prefix.to_s == '.' ? '' : "#{rel_prefix}/"
   end
 
   # called standalone by servelet
-  def generate_class(klass, template_file = nil)
+  def generate_class(klass, template_file = nil) # :nodoc:
     setup
     current = klass
     template_file ||= @template_dir + 'class.rhtml'
@@ -108,7 +112,7 @@ class Oldweb
   end
 
   # Generate a documentation file for each class and module
-  def generate_class_files
+  def generate_class_files # :nodoc:
     setup
     template_file = @template_dir + 'class.rhtml'
     current = nil
@@ -122,7 +126,7 @@ class Oldweb
   end
 
   # Generate a documentation file for each file
-  def generate_file_files
+  def generate_file_files # :nodoc:
     setup
     @files.each do |file|
       generate_page(file) if file.text?
@@ -130,7 +134,7 @@ class Oldweb
   end
 
   # Generate a page file for +file+
-  def generate_page(file, out_file = @outputdir + file.path)
+  def generate_page(file, out_file = @outputdir + file.path) # :nodoc:
     setup
     template_file = @template_dir + 'page.rhtml'
     rel_prefix = rel_path(out_file)
@@ -152,7 +156,7 @@ class Oldweb
   end
 
   # Generates the 404 page for the RDoc servlet
-  def generate_servlet_not_found(message)
+  def generate_servlet_not_found(message) # :nodoc:
     setup
     template_file = @template_dir + 'servlet_not_found.rhtml'
     rel_prefix = ''
@@ -164,7 +168,7 @@ class Oldweb
   end
 
   # Generates the servlet root page for the RDoc servlet
-  def generate_servlet_root(installed)
+  def generate_servlet_root(installed) # :nodoc:
     setup
 
     template_file = @template_dir + 'servlet_root.rhtml'
@@ -178,7 +182,7 @@ class Oldweb
     e!(e, "error generating servlet_root: #{e.message} (#{e.class})")
   end
 
-  def generate_table_of_contents
+  def generate_table_of_contents # :nodoc:
     setup
     template_file = @template_dir + 'table_of_contents.rhtml'
     out_file = @outputdir + 'table_of_contents.html'
@@ -190,7 +194,7 @@ class Oldweb
     e!(e, "error generating table_of_contents.html: #{e.message} (#{e.class})")
   end
 
-  def setup
+  def setup # :nodoc:
     return if @outputdir
     @outputdir = Pathname.new(@options.op_dir).expand_path(@base_dir)
     return unless @store
@@ -201,7 +205,7 @@ class Oldweb
   end
 
   # Creates a template from its components and the +body_file+.
-  def assemble_template(body_file)
+  def assemble_template(body_file) # :nodoc:
     body = body_file.read
     head = @template_dir + '_head.rhtml'
     tail = @template_dir + '_tail.rhtml'
@@ -211,7 +215,7 @@ class Oldweb
 
   # Renders the ERb contained in +file_name+ relative to the template
   # directory and returns the result based on the current context.
-  def render(file_name)
+  def render(file_name) # :nodoc:
     template_file = @template_dir + file_name
     template = template_for(template_file, false, RDoc::ERBPartial)
     template.filename = template_file.to_s
@@ -222,7 +226,7 @@ class Oldweb
   # it out to +out_file+.
   # Both +template_file+ and +out_file+ should be Pathname-like objects.
   # An io will be yielded which must be captured by binding in the caller.
-  def render_template(template_file, out_file = nil) # :yield: io
+  def render_template(template_file, out_file = nil) # :nodoc:
     io_output = out_file && !@dry_run && @file_output
     erb_klass = io_output ? RDoc::ERBIO : ERB
     template = template_for(template_file, true, erb_klass)
@@ -242,14 +246,14 @@ class Oldweb
 
   # Creates the result for +template+ with +context+.  If an error is raised a
   # Pathname +template_file+ will indicate the file where the error occurred.
-  def template_result(template, context, template_file)
+  def template_result(template, context, template_file) # :nodoc:
     template.filename = template_file.to_s
     template.result(context)
   rescue NoMethodError => e
     e!(e, "Error while evaluating #{template_file.expand_path}: #{e.message}")
   end
 
-  def template_for(file, page = true, klass = ERB)
+  def template_for(file, page = true, klass = ERB) # :nodoc:
     template = @template_cache[file]
 
     return template if template
@@ -268,11 +272,11 @@ class Oldweb
     @template_cache[file] = template
   end
 
-  def e!(e, msg)
+  def e!(e, msg) # :nodoc:
     raise RDoc::Error, msg, e.backtrace
   end
 
-  def method_srclink(m)
+  def method_srclink(m) # :nodoc:
     url = @old_vcs_url or return ""
     line = m.line or return ""
     path = URI.escape(m.file_name)
@@ -280,7 +284,7 @@ class Oldweb
   end
 
   # reach into RDoc internals to generate less HTML
-  module LessHtml
+  module LessHtml # :nodoc:
     def accept_verbatim(verbatim)
       @res << "\n<pre>#{CGI.escapeHTML(verbatim.text.rstrip)}</pre>\n"
     end
@@ -296,8 +300,10 @@ class Oldweb
   end
 end
 
+# :stopdoc:
 class RDoc::Markup::ToHtml # :nodoc:
   remove_method :accept_heading
   remove_method :accept_verbatim
   include Oldweb::LessHtml
 end
+# :startdoc:
diff --git a/lib/rdoc/discover.rb b/lib/rdoc/discover.rb
index e497514..9450f42 100644
--- a/lib/rdoc/discover.rb
+++ b/lib/rdoc/discover.rb
@@ -1,5 +1,7 @@
+# :stopdoc:
 begin
   gem 'rdoc', '~> 4.1'
   require_relative '../olddoc'
 rescue Gem::LoadError
 end unless defined?(Olddoc)
+# :startdoc:
-- 
EW