lib/rdoc/generator/markdown.rb in rdoc-markdown-0.1.14 vs lib/rdoc/generator/markdown.rb in rdoc-markdown-0.2

@@ -5,14 +5,18 @@
 require "pathname"
 require "erb"
 require "reverse_markdown"
 require 'extralite'
 require 'active_support/core_ext/string/inflections'
+require 'unindent'
 
 class RDoc::Generator::Markdown
   RDoc::RDoc.add_generator self
 
+  ##
+  # Defines a constant for directory where templates could be found
+
   TEMPLATE_DIR = File.expand_path(
     File.join(File.dirname(__FILE__), "..", "..", "templates")
   )
 
   ##
@@ -41,19 +45,25 @@
   end
 
   # this alias is required for rdoc to work
   alias_method :file_dir, :class_dir
 
+  ##
+  # Initializer method for Rdoc::Generator::Markdown
+
   def initialize(store, options)
     @store = store
     @options = options
 
     @base_dir = Pathname.pwd.expand_path
 
     @classes = nil
   end
 
+  ##
+  # Generates markdown files and search index file
+
   def generate
     setup
 
     debug("Create directory #{@output_dir}")
 
@@ -71,20 +81,27 @@
   private
 
   attr_reader :options
   attr_reader :output_dir
 
+  ##
+  # This method is used to output debugging information in case rdoc is run with --debug parameter
+
   def debug(str = nil)
     if $DEBUG_RDOC
       puts "[rdoc-markdown] #{str}" if str
       yield if block_given?
     end
   end
 
-  def emit_sqlite
-    db = Extralite::Database.new("#{output_dir}/index.db")
+  ##
+  # This class emits a search index for generated documentation as sqlite database
+  #
 
+  def emit_sqlite(name="index.db")
+    db = Extralite::Database.new("#{output_dir}/#{name}")
+
     db.execute <<-SQL
       create table contentIndex (
         id INTEGER PRIMARY KEY,
         name TEXT,
         type TEXT,
@@ -157,20 +174,26 @@
 
       File.write(out_file, result)
     end
   end
 
+  ##
+  # Takes a class name and converts it into a Pathname
 
-  private
-
   def turn_to_path(class_name)
     "#{class_name.gsub("::", "/")}.md"
   end
 
+  ##
+  # Converts HTML string into a Markdown string with some cleaning and improvements.
+
   def markdownify(input)
     md= ReverseMarkdown.convert input, github_flavored: true
 
+    # unintent multiline strings
+    md.unindent!
+
     # Replace .html to .md extension in all markdown links
     md = md.gsub(/\[(.+)\]\((.+).html(.*)\)/) do |_|
       match = Regexp.last_match
 
       "[#{match[1]}](#{match[2]}.md#{match[3]})"
@@ -179,10 +202,15 @@
     # clean up things, to make it look neat.
 
     md.gsub("[↑](#top)", "").lstrip
   end
 
+  # Aliasing a shorter method name for use in templates
   alias_method  :h, :markdownify
+
+  ##
+  # Prepares for document generation, by creating required folders and initializing variables.
+  # Could be called multiple times.
 
   def setup
     return if instance_variable_defined?(:@output_dir)
 
     @output_dir = Pathname.new(@options.op_dir).expand_path(@base_dir)