Generate toplevel docs correctly

spec/compiler/crystal/tools/doc/generator_spec.cr

@@ -0,0 +1,85 @@
+require "../../../spec_helper"
+
+describe Doc::Generator do
+  describe "must_include_toplevel?" do
+    it "returns false if program has nothing" do
+      program = Program.new
+      generator = Doc::Generator.new program, ["foo"], ".", nil
+      doc_type = Doc::Type.new generator, program
+
+      generator.must_include_toplevel?(doc_type).should be_false
+    end
+
+    it "returns true if program has constant" do
+      program = Program.new
+      generator = Doc::Generator.new program, ["foo"], ".", nil
+      doc_type = Doc::Type.new generator, program
+
+      constant = Const.new program, program, "Foo", 1.int32
+      constant.add_location Location.new "foo", 1, 1
+      program.types[constant.name] = constant
+
+      generator.must_include_toplevel?(doc_type).should be_true
+    end
+
+    it "returns false if program has constant which is defined in other place" do
+      program = Program.new
+      generator = Doc::Generator.new program, ["foo"], ".", nil
+      doc_type = Doc::Type.new generator, program
+
+      constant = Const.new program, program, "Foo", 1.int32
+      constant.add_location Location.new "bar", 1, 1
+      program.types[constant.name] = constant
+
+      generator.must_include_toplevel?(doc_type).should be_false
+    end
+
+    it "returns true if program has macro" do
+      program = Program.new
+      generator = Doc::Generator.new program, ["foo"], ".", nil
+      doc_type = Doc::Type.new generator, program
+
+      a_macro = Macro.new "foo"
+      a_macro.location = Location.new "foo", 1, 1
+      program.add_macro a_macro
+
+      generator.must_include_toplevel?(doc_type).should be_true
+    end
+
+    it "returns false if program has macro which is defined in other place" do
+      program = Program.new
+      generator = Doc::Generator.new program, ["foo"], ".", nil
+      doc_type = Doc::Type.new generator, program
+
+      a_macro = Macro.new "foo"
+      a_macro.location = Location.new "bar", 1, 1
+      program.add_macro a_macro
+
+      generator.must_include_toplevel?(doc_type).should be_false
+    end
+
+    it "returns true if program has method" do
+      program = Program.new
+      generator = Doc::Generator.new program, ["foo"], ".", nil
+      doc_type = Doc::Type.new generator, program
+
+      a_def = Def.new "foo"
+      a_def.location = Location.new "foo", 1, 1
+      program.add_def a_def
+
+      generator.must_include_toplevel?(doc_type).should be_true
+    end
+
+    it "returns false if program has method which is defined in other place" do
+      program = Program.new
+      generator = Doc::Generator.new program, ["foo"], ".", nil
+      doc_type = Doc::Type.new generator, program
+
+      a_def = Def.new "foo"
+      a_def.location = Location.new "bar", 1, 1
+      program.add_def a_def
+
+      generator.must_include_toplevel?(doc_type).should be_false
+    end
+  end
+end

src/compiler/crystal/tools/doc/generator.cr

@@ -42,7 +42,7 @@ class Crystal::Doc::Generator
     types = collect_subtypes(@program)
 
     program_type = type(@program)
-    if program_type.class_methods.any? { |method| must_include? method }
+    if must_include_toplevel? program_type
       types.insert 0, program_type
     end
 
@@ -137,7 +137,7 @@ class Crystal::Doc::Generator
     must_include? a_def.location
   end
 
-  def must_include?(a_macro : Macro)
+  def must_include?(a_macro : Doc::Macro)
     must_include? a_macro.macro
   end
 
@@ -147,6 +147,16 @@ class Crystal::Doc::Generator
     must_include? a_macro.location
   end
 
+  def must_include?(constant : Constant)
+    must_include? constant.const
+  end
+
+  def must_include?(const : Crystal::Const)
+    return false if nodoc?(const)
+
+    const.locations.try &.any? { |location| must_include? location }
+  end
+
   def must_include?(location : Crystal::Location)
     case filename = location.filename
     when String
@@ -162,6 +172,15 @@ class Crystal::Doc::Generator
     false
   end
 
+  def must_include_toplevel?(program_type : Type)
+    toplevel_items = [] of Method | Macro | Constant
+    toplevel_items.concat program_type.class_methods
+    toplevel_items.concat program_type.macros
+    toplevel_items.concat program_type.constants
+
+    toplevel_items.any? { |item| must_include? item }
+  end
+
   def nodoc?(str : String?)
     return false unless str
     str.starts_with?(":nodoc:") || str.starts_with?("nodoc")