markdown_ruby_documentation 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0195aa8a642b4e01747ef74e449c4a0e0195fcc5
-  data.tar.gz: c752bf835f1c6fbf3bbf5ed968cc35a3810bb930
+  metadata.gz: a68bd5fe5f99c18c45c27e6181f8496cfeebb5d7
+  data.tar.gz: 09a1174ba49e82834e7aca0daffb530f7a685d12
 SHA512:
-  metadata.gz: a736068cff89585b1efa8dbce9dc0854effea63f90a38819dbe75c406594240824162f0e297c6095054e65824caeae4abf47f19d76fecafc7b445caa9566ca92
-  data.tar.gz: c2ce815983eb44535d554e0599a61588a9f1d7adff1892ad52330f3256fb6eb7a28575af2a198aa625de755f34e3483df4f920dc1aa1ad4e6f32c81673d2dd5b
+  metadata.gz: 8f8121c1c700e8a563a107cecb0186c74bce3e4f9437f5eb6466a5f3da223ee2ff8efd05767420065d169ef90f403a1110ee4c0bf6ca0f981720bb5c02711458
+  data.tar.gz: afccbc3dc8db8ce1fd535207b70500e9998e0a6ea4c61e0e8d77b8b4a72110a1480cedb717b4d8e3b468fc4dca1c67bf2898f1ac1731412d61318fc71a622ac5

data/lib/markdown_ruby_documentation/class_level_comment.rb

@@ -0,0 +1,54 @@
+module MarkdownRubyDocumentation
+  class ClassLevelComment
+    attr_reader :subject
+    include TemplateParser::Parsing
+    def initialize(subject)
+      @subject = subject
+    end
+
+    def call(interface)
+      _method = interface.reject do |_, meth|
+        meth[:method_object].is_a?(NullMethod)
+      end.first
+      if _method
+        filename, lineno = _method[1][:method_object].to_proc.source_location
+        comment = extract_dsl_comment(strip_comment_hash(comment(filename, lineno)+"\n"))
+        interface[:class_level_comment] = { text: comment }
+      end
+      interface
+    end
+
+    def comment(filename, lineno)
+      method_to_top_of_file = File.read(filename).split("\n")[0..(lineno-1)]
+      subject_start_line = find_start_of_subject(method_to_top_of_file, filename)
+      extract_last_comment(method_to_top_of_file[0..(subject_start_line-1)].reverse).reverse.join("\n")
+    end
+
+    def find_start_of_subject(method_to_top_of_file, filename)
+      method_to_top_of_file.each_with_index do |line, index|
+        if line =~ /#{subject.class.to_s.downcase} #{subject.name.split("::").last}/
+          return index
+        end
+      end
+      puts /#{subject.class} #{subject.name.split("::").last}/
+      puts method_to_top_of_file
+      raise "class #{subject.name} not found in #{filename}"
+    end
+
+    def extract_last_comment(lines)
+      buffer = []
+
+      lines.each do |line|
+        # Add any line that is a valid ruby comment,
+        # but clear as soon as we hit a non comment line.
+        if line =~ /^\s*#/
+          buffer << line.lstrip
+        else
+          return buffer
+        end
+      end
+
+      buffer
+    end
+  end
+end

data/lib/markdown_ruby_documentation/generate.rb

@@ -90,6 +90,7 @@ module MarkdownRubyDocumentation
           RejectBlankMethod,
           GitHubLink.new(subject: subject),
           ConstantsPresenter.new(subject),
+          ClassLevelComment.new(subject),
           MarkdownPresenter.new(summary: summary, title_key: section_key),
         ]
       end

data/lib/markdown_ruby_documentation/markdown_presenter.rb

@@ -14,7 +14,11 @@ module MarkdownRubyDocumentation
     def call(items=nil)
       @items ||= items
       return "" if nothing_to_display?
-      md = ["# #{summary.title}", "#{summary.summary}\n".gsub(/\n\n\n/, "\n\n"), instances_methods, class_methods, "#{null_methods}\n".gsub(/\n\n\n/, "\n\n")].join("\n").gsub(/[\n]+\Z/, "\n\n")
+      md = ["# #{summary.title}", "#{summary.summary}\n".gsub(/\n\n\n/, "\n\n"), class_level_comment, instances_methods, class_methods, "#{null_methods}\n".gsub(/\n\n\n/, "\n\n")]
+             .reject(&:empty?)
+             .join("\n")
+             .gsub(/[\n]{3,}/, "\n\n")
+             .gsub(/[\n]+\Z/, "\n\n")
       other_types!
       md
     end
@@ -25,6 +29,16 @@ module MarkdownRubyDocumentation
       @item_types ||= items.group_by { |_, hash| hash[:method_object].class.name }
     end
 
+    def class_level_comment
+      @class_level_comment ||= (items.delete(:class_level_comment) || {})
+
+      if @class_level_comment[:text]
+        "#{@class_level_comment[:text]}\n"
+      else
+        ""
+      end
+    end
+
     def instances_methods
       @instance_methods ||= item_types.delete("MarkdownRubyDocumentation::InstanceMethod")  || {}
       @instance_methods.map do |name, hash|
@@ -47,7 +61,7 @@ module MarkdownRubyDocumentation
       if md.blank?
         ""
       else
-        "## Reference Values\n" << md
+        "\n## Reference Values\n" << md
       end
     end
 
@@ -56,7 +70,7 @@ module MarkdownRubyDocumentation
     end
 
     def nothing_to_display?
-      [instances_methods, class_methods, null_methods].all?(&:empty?)
+      [class_level_comment, instances_methods, class_methods, null_methods].all?(&:empty?)
     end
   end
 end

data/lib/markdown_ruby_documentation/summary.rb

@@ -1,32 +1,34 @@
-class Summary
-  attr_reader :erb_methods_class, :subject
+module MarkdownRubyDocumentation
+  class Summary
+    attr_reader :erb_methods_class, :subject
 
-  def initialize(subject:, erb_methods_class:)
-    @subject           = subject
-    @erb_methods_class = erb_methods_class
-  end
+    def initialize(subject:, erb_methods_class:)
+      @subject           = subject
+      @erb_methods_class = erb_methods_class
+    end
 
-  def title
-    ancestors = subject.ancestors.select do |klass|
-      klass.is_a?(Class) && ![BasicObject, Object, subject].include?(klass)
-    end.sort_by { |klass| klass.name }
-    [format_class(subject), *ancestors.map { |a| create_link(a) }].join(" < ")
-  end
+    def title
+      ancestors = subject.ancestors.select do |klass|
+        klass.is_a?(Class) && ![BasicObject, Object, subject].include?(klass)
+      end.sort_by { |klass| klass.name }
+      [format_class(subject), *ancestors.map { |a| create_link(a) }].join(" < ")
+    end
 
-  def summary
-    descendants = ObjectSpace.each_object(Class).select { |klass| klass < subject && !klass.name.include?("InstanceToClassMethods") }.sort_by { |klass| klass.name }
+    def summary
+      descendants = ObjectSpace.each_object(Class).select { |klass| klass < subject && !klass.name.include?("InstanceToClassMethods") }.sort_by { |klass| klass.name }
 
-    descendants_links = descendants.map { |d| create_link(d) }.join(", ")
-    "Descendants: #{descendants_links}" if descendants.count >= 1
-  end
+      descendants_links = descendants.map { |d| create_link(d) }.join(", ")
+      "Descendants: #{descendants_links}" if descendants.count >= 1
+    end
 
-  private
+    private
 
-  def create_link(klass)
-    erb_methods_class.link_to_markdown(klass.to_s, title: format_class(klass))
-  end
+    def create_link(klass)
+      erb_methods_class.link_to_markdown(klass.to_s, title: format_class(klass))
+    end
 
-  def format_class(klass)
-    klass.name.titleize.split("/").last
+    def format_class(klass)
+      klass.name.titleize.split("/").last
+    end
   end
 end

data/lib/markdown_ruby_documentation/version.rb

@@ -1,3 +1,3 @@
 module MarkdownRubyDocumentation
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/markdown_ruby_documentation.rb

@@ -18,6 +18,7 @@ require "markdown_ruby_documentation/method/null_method"
 require "markdown_ruby_documentation/write_markdown_to_disk"
 require "markdown_ruby_documentation/default_erb_methods"
 require "markdown_ruby_documentation/constants_presenter"
+require "markdown_ruby_documentation/class_level_comment"
 require "ruby-progressbar"
 require "active_support/core_ext/string"
 require "method_source"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: markdown_ruby_documentation
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Dustin Zeisler
@@ -115,6 +115,7 @@ files:
 - bin/setup
 - lib/github-markdown.css
 - lib/markdown_ruby_documentation.rb
+- lib/markdown_ruby_documentation/class_level_comment.rb
 - lib/markdown_ruby_documentation/constants_presenter.rb
 - lib/markdown_ruby_documentation/default_erb_methods.rb
 - lib/markdown_ruby_documentation/generate.rb